• Get to the point. Use straightforward language.
  • Show examples. It’s more effective to use examples rather than only using prose.
  • Use figurative language sparingly. Like macros, metaphors can be useful, but too many can make your writing difficult to follow. (metaphor usage intentional)
  • Remember: Users come to your documentation to learn. If you want to be creative in your technical writing or provide a deeper explanation for your philosophies, perhaps consider other creative mediums (personal blogs, talks) instead of documentation.
  • Do not make too many assumptions about the reader’s background.

An extra rule for me and maybe the other Americans out there:

  • Do not assume the reader is an American English speaker.

Whenever I write documentation, I try to imagine a frazzled employee who needs to juggle project meetings, PR reviews, mentoring, deadlines, all on top of regular programming tasks (me, essentially). I choose concise, direct language because often times, the reader needs to get something done quickly so they can cross off the other things on their endless todo list.

When writing documentation, a little empathy for readers goes a long way.