Documentation is part of the product

Consider the documentation as a component of your product, i.e. don’t package it as an external product or as an option.

In software development, your “product” is usually made of the software, which itself is usually based on source code.

Include documentation in production workflow

Since documentation is part of the product, include it in your production workflow:

  • add it to the definition of done (see scrum development method [1])
  • package and release documentation with code
  • a problem in documentation is called a bug, as any problem in code
  • changes in documentation can be prioritized as any feature
  • a new version of documentation implies a new version of the product.

Synchronize code and documentation

Make sure that, for a given version of your product, you can get the adequate version of the documentation, and vice-versa.

Easiest way to do so is to manage documentation and code in the same version control repository.

Otherwise, at least create releases of documentation when you create releases of the product. And you should automate this task.

Use Sphinx instead of wikis

Several platforms, such as Github, propose a wiki service. It’s a true temptation to use a wiki to host documentation:

  • it’s collaborative,
  • it can be versionned,
  • it’s a good place to receive contributions. It’s visible and easy to use.

So it seems suitable to serve documentation, but:

  • it’s easier to synchronize versions and branches of documentation and code when they live in the same repository. Will you create a branch or version of wiki for each branch or version of code?
  • wiki is a kind of “live” content. It’s meant to receive continuous and spontaneous contributions. It is not meant to be included in a development workflow with tickets, commits, code reviews, merges, releases and support.

So, for documentation, use tools like Sphinx [2] rather than wiki services.

On the contrary, wikis may be more suitable than “static” documentation for use cases where “live content” or “community-made content” are most valuable features:

  • encyclopedia
  • community articles about a web application which is live (only current production version is important).