Building Beginner-Friendly API Tutorials

@alainakafkes

@alainakafkes

I work at Medium.

I write a lot.

More: alainakafk.es

🙋🏿‍♂️ 🙅🏼 🤦🏻‍♂️ 💁🏽

What do these people have in common?

@alainakafkes

🙋🏿‍♂️ 🙅🏼 🤦🏻‍♂️ 💁🏽

They're beginners who read your API docs.

@alainakafkes

How can our APIs get

less 🤦🏻‍♂️ and more 💁🏽?

@alainakafkes

Not just docs... Beginner-friendly ✨tutorials✨

@alainakafkes

Tutorials are the gateway to an API.

@alainakafkes

But bad tutorials will backfire on beginners.

@alainakafkes

➡️ 🙅🏼 🤦🏻‍♂️ ⬅️

Remember these two?

@alainakafkes

🤦🏻‍♂️

Overwhelmed by errors

Frustrated by missing info

🙅🏼

@alainakafkes

Writers are cursed with

🔮knowledge🔮

@alainakafkes

   The Writer's Curse

• Writers know an API intimately
• Readers approach an API with fresh eyes

@alainakafkes

Writers assume.

@alainakafkes

Readers leave.

@alainakafkes

The API suffers.

@alainakafkes

So, how do we write to retain new API users?

@alainakafkes

It's all in the proofreading.

@alainakafkes

Proofreading is the writer's chance to look at a tutorial anew.

@alainakafkes

Proofreading gives the writer space to think like a reader.

@alainakafkes

There are proofreading steps you can take to build better tutorials.

@alainakafkes

Offer a quick start.

1️⃣

@alainakafkes

1️⃣ Quick Start

Provide new user with commented, easy-to-copy-paste code.

@alainakafkes

1️⃣ Quick Start

Painless introduction
➡️ newbie confidence.

@alainakafkes

1️⃣ Quick Start

clarifai.com/developer/quick-start

Perform a tech audit.

2️⃣

@alainakafkes

2️⃣ Tech Audit

Code alongside your tutorial and see what happens.

@alainakafkes

2️⃣ Tech Audit

If the writer can't build the final product from scratch, no one can!

@alainakafkes

2️⃣ Tech Audit

twilio.com/blog/2017/09/send-text-messages-golang.html

Remember your environment.

3️⃣

@alainakafkes

3️⃣ Environment

No two environments are exactly the same.

@alainakafkes

3️⃣ Environment

Env assumptions
➡️ spooky errors.

@alainakafkes

3️⃣ Environment

Challenge underlying env assumptions in each code block.

@alainakafkes

3️⃣ Environment

Simple reminders never hurt!

@alainakafkes

3️⃣ Environment

bit.ly/intro-api

Share next steps.

4️⃣

@alainakafkes

4️⃣ Next Steps

@alainakafkes

Tell the beginner what to do after the tutorial.

4️⃣ Next Steps

@alainakafkes

What should the reader do when they finish?

4️⃣ Next Steps

@alainakafkes

Where can the reader find more information?

4️⃣ Next Steps

@alainakafkes

To whom can the reader ask questions?

4️⃣ Next Steps

github.com/slackapi/Slack-Python-Onboarding-Tutorial

Anticipate errors.

5️⃣

@alainakafkes

5️⃣ Errors

@alainakafkes

Identify places where you expect to see a successful output.

5️⃣ Errors

@alainakafkes

Write the "else" case.

5️⃣ Errors

twilio.com/blog/2017/09/send-text-messages-golang.html

Stick to the
standard library.

6️⃣

@alainakafkes

6️⃣ Standard Library

@alainakafkes

Beginners don't write idiomatic code.

6️⃣ Standard Library

@alainakafkes

Write standard, commented, verbose code examples.

6️⃣ Standard Library

@alainakafkes

Limit dependencies.

6️⃣ Standard Library

@alainakafkes

If you leave the standard library, explain why.

6️⃣ Standard Library

heml.io/docs/getting-started/guide

Use inclusive language.

7️⃣

@alainakafkes

7️⃣ Inclusive Language

@alainakafkes

Choose words that welcome beginners from all backgrounds.

7️⃣ Inclusive Language

@alainakafkes

Define jargon and acronyms, or avoid them entirely.

7️⃣ Inclusive Language

@alainakafkes

Stick to gender neutral pronouns like "you," "they," and "we."

7️⃣ Inclusive Language

open.buffer.com/inclusive-language-tech

We've emerged with tips to write beginner-friendly tutorials.

@alainakafkes

Remember: welcoming writing is forged through proofreading.

@alainakafkes

Proofreading improves tutorial quality.

@alainakafkes

Quality tutorials lead to beginner retention.

@alainakafkes

Retention fosters a healthy community.

@alainakafkes

Community augments API user growth.

@alainakafkes

🙋🏿‍♂️ 👩‍💻 🙆🏻‍♂️ 💁🏽

Want these folks to be your API newcomers?

@alainakafkes

Make API tutorials beginner-friendly by proofreading.

@alainakafkes

Thank you!

@alainakafkes

bit.ly/api-tutorials