TIL
|
01-06-2019
2 min read
Writing Documentation

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?

Tooling

  • 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.

Inspiration

  • 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.

Reference