You have to sell what it is you’re building in your documentation. It’s not just describing what it is and how to use it. It’s about telling interesting stories.
Rico Sta. Cruz
Highlights
Write like a human, not a machine: Don’t be afraid to be funny, creative, and a bit silly.
Write as simply as possible: Simple words, short sentences, bulleted lists and/or numbered lists, concrete examples.
Make easy to contribute: Provide a simple way to anybody extend the documentation.
Illustrate with examples: Add examples for your words, keep it up to date.
Connect your documentation: Don’t write linearly, just hyperlink other sections for connecting content, all the time.
The vacation test 🏝
If you go on a long vacation now with no internet access, can someone on your team read the doc and implement it as you intended?
