Post by @stani • Hey
Developers, what makes docs good?
Comments
- Good practical examples
- Examples with the ability (if possible) to run and modify them right from the docs themself. I love API docs that let you run customizable curl requests straight from the doc page.
- clarity and brevity are two things that I value
but above all that it has a good search engine and repositories for each example
- GOOD DOCS ARE ESSENTIALLY GOOD PRODUCTS.
Most don't have this mindset and think of docs as an afterthought or a waste of resources.
This is an oversimplification as docs serve different types of devs w/ their own needs, but as a general rule good docs:
1. Get Constantly updated
No one likes to read outdated docs.
2. Have a clearly separated layout with distinct purposes
Each part of the docs serves a different purpose and good docs have distinct sections that should stand on their own and not get mixed with one another.
I always like to revisit this video for good docs structure: https://www.youtube.com/watch?v=t4vKPhjcMZg
TLDR;
- Tutorials (Learn)
- Guides (Solve Use Cases)
- References (API/SDK details + Changelog)
- Discussion (Technical Blogs discussing, sometimes external topics)
3. Contains 95% code + 5 % text
Most devs don't read docs end-to-end like novels, most just scroll to the code and copy-paste instead of reading paragraphs
Thus, dominate the docs with code samples with 1 or 2 sentences for each, AVOID PARAGRAPHS!
4. Contains lots of demos
show (not tell) users through Online IDE (e.g. CodeSandbox/Stackblitz/etc.) or videos of how the product works in production
5. Is written in a technical manner, not a sales one
Docs are technical guides and therefore should be purely informative instead of "selling".
Besides devs don't like to be sold something, writing it like sales material does not make sense at the docs stage, since they already passed that stage when looking at the main site.
Docs is where devs always search on how to use the product.
- Good structure, snippets where needed, not using adjectives, search option, indexing other pages when referencing them.
But nowadays using language models to ask documentation based questions is almost unbeatable. So integrating language model into search would be a huge step forward.
- gm
- Embed debugger
- GM!
- Accuracy
- Accuracy
- A good *working* search field
- Dark mode
- @yosephks.lens
- Powerpoints? 😂😂
- Up to date
What you can do (meaning, use cases where using this makes sense)
What you can't do (meaning, use cases where using this either doesn't make sense or isn't possible)
Simple examples + link to repo
Realworld examples + link to repo
Alternatives & inspirations