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
🙅🏼
Writer != Reader
@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
