September 12, 2018
- 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?
- readability – Measure the readability in a text.
- write-music – Visualise sentence length.
- ClearText – A text editor that only allows the 1,000 most common words in English.
- beautiful-docs – Pointers to useful, well-written, and otherwise beautiful documentation.
- feedmereadmes – Free README editing+feedback to make your open-source projects grow.
- awesome-readme – A curated list of awesome READMEs.