Write the docs meetup: developers documentation, your hidden strength - Frédéric Harper

Tags: writethedocs, python

(One of my summaries of the Amsterdam *write the docs* meetup).

If you have a product, you need good developer documentation. “It is an integral part of your product: one cannot exist without the other”. You might have the best product, but if people don’t know how to use it, it doesn’t matter.

What he tells developers: good documentation reduces support tickets and angry customers. You should be able to “sell” good documentation to your company: it saves money and results in more sales.

Some notes on documentation contents:

  • You need a search function. The first thing you need to add.

  • Think about John Snow (game of thrones): “you know nothing, John Snow”. Be detailed in your instructions, they’ll need it. Start with the assumption that the user knows nothing about your program. Advanced users can easily skip those parts.

  • Have a proper architecture/structure. Simply having a “home” link to get back to the start already helps. Add a “getting started” section with step-by-step instructions to get something simple running. And detailed how-to guides where you go into depth.

  • Show a table of contents of the current page.

  • Keep the docs of previous versions available.

  • Take great screenshots. Docs should have great quality and it especially shows in the screenshots.

  • Don’t show off your language skills too much. Keep the language simple. Not everyone will have your documentation’s language as their native language.

  • Test the code in your documentation! There’s nothing more irritating than errors in example code. And keep it up to date. Especially watch out when the software gets updated. Do you give your documentation time to get updated?

Some extra notes:

  • Make your docs accessible for people with disabilities.

  • Are your docs fast? Load times help you get ranked higher in search engines.

  • Some people read your documentation on their phones: does it work there?

  • Try to make your docs open source. You might get an occasional fix. And perhaps more feedback.