If you’re interested in learning more about writing good documentation, there are tons of useful things you can read next! In particular, there’s a ton of useful stuff on the Write the Docs website, including videos and the archive of the newsletter.
1. Start with what the reader needs
- This is a really fundamental principle that I learned a lot about from GDS, and specifically from the work that Sarah Richards and others did on content design there. Some useful content from them.
- Riona MacNamara on what documentation is for
2. Write less
3. Write the outline first and 4. Rubber ducking for docs
These are techniques I use but I don’t have anything written up about them yet - sorry!
5. Write readably
- This section of the talk with a lot more detail, as a blog post: Editing
- An extended version of this talk, focusing on the Haskell ecosystem, is on YouTube.
- A worked example of editing to make something clearer
- Tons of things about readability I learnt, again, from GDS: GOV.UK content design guidance
- Kelly O’Brien on making writing engaging