Be directive

Let’s quote the Zen of Python [1]:

  • Special cases aren’t special enough to break the rules.
  • Although practicality beats purity.
  • There should be one– and preferably only one –obvious way to do it.

Then apply it to documentation:

  • documentation is the obvious place to get information.
  • documentation tells the rules.
  • it covers the (only) pragmatic way to go.

Don’t make me think

  • Sometimes users don’t need to understand everything. They just want something that works. So give them a straightforward recipe that just works.
  • Don’t try to explain everything. You will become verbose. Users will feel bored, and if they are in some lazy mood, they may get out.
  • You’d better make an user-friendly product than explain its usage in documentation.
  • You’d better improve code readability than explain code in documentation.

Support driven documentation

  • Focus on what have been proven functional. No matter if it is not perfect or generic. If it works, it’s enough.
  • Support best practices only. Refuse what breaks conventions.
  • If something important is wrong with existing documentation, fix it. But don’t lose time and energy to support what has already been documented.

Make choices

Don’t try to create a perfect product. You can create and maintain a sufficient one. It’s a matter of vision, priorities, choices... and iterations.

Write down these choices in the documentation. The adequate place to discuss and plan these choices is the ticket system (user stories, bugtracker), not the documentation.