Goal-Driven Documentation by Tyler Blain:
Focus on the use cases and needs the user has rather than documenting the individual features Not: “how to adjust speed” or “how to change the direction” but rather “how to drill a hole in a flat surface”
A cookbook style approach. We write documentation for humans and humans have needs and problems they want to solve.
I’ve written about this in my blog post Documentation: man vs tldr
Use cases give developers also ideas and inspiration for what they can do with the software and sparks extra imagination.
Demos are nice for showcasing how to practically implement something.
“Bad documentation is bad” quote by Leigh Momii on Twitter
Even if a developer cares about docs, they often don’t have time to write them unless that’s your main job.
Small things you can do to improve your docs as a developer:
- Words we use matter (see Read the Docs podcast with Lucie Le Naourtodo)
- Insensitive language: gendered language in examples (he/she/they)
- Problematic terms: master/slave or whitelist/blacklist
- Think before you type
- See if you can find alternatives that are generic and more semantic
- Avoid “simply” or “easy” or “just” - we can just skip these words and use linters to automatically catch them
- Show, don’t tell: if you believe something takes 5 minutes, record a video doing it and then find someone who has never used your tools and see if it still holds true Linters are not a replacement to human editors
- alex-js
- write-good
- vale.sh Avoid humor
- It’s very culture dependent and can be misunderstood
- Can confuse your readers
People often come to documentation when they are frustrated and need help. It’s an important factor to keep in mind.
Plain language is better can complex, bloated language. Hemingway app can help with that.
“No one has ever complained that something was too easy to read”, quote from Ashley Bischoff
Documentation can help make the experience better when people run into unexpected errors. - Explain common known errors: what might happen, potential reasons for why and what to do next - Also put them next to the relevant parts of guides and tutorials where user might run into them so they don’t have to go search for them and be confused
Developers know too much about the tools they’ve built.
“Everyone is a beginner at some point.” quote by Carolyn Stransky
Take a step back, ask someone (like a colleague from another project or user from community) to use your documentation and see if they can solve issues.
Code snippets should never be screenshots!
- More accessible
- Can be copy-pasted around
- <code>
for inline, <pre>
for blocks
Maintaining documentation - Every page should have easy to follow structure, for example: 1. Explain a feature 2. Describe use cases 3. Recommend tooling - I also like community provided snippets like PHP docs have - Explain if there are specific use cases where your tool would not be a good fit
Good guidelines: We aim for: - Accuracy and consistency - Honest (we communicate pros and cons to build trust), helpful (we want users to succeed) and human (we want to feel familiar and approachable)