Writing documentation is seldom fun for developers and much useless documentation is written. I want to provide some guidelines helping to focus your project documentation efforts on useful stuff instead of following a set of dogmatic rules to plainly fulfill requirements.
Probably written many times before but nevertheless often neglected:
- Avoid untouched documentation templates, e.g.
// This is a getter for A. They only clutter the code hurting developers instead of providing value.
- Do not document every class, method, file etc. blindly. Focus on all API classes et al. to be used by other (external) developers.
- Do not document what the code does, it should speak for itself. Rather explain why a certain algorithm or data structure is used. Try to communicate design decisions.
- Check comments everytime you touch documented code and update them if necessary. Outdated documentation hurts more than its worth so if docs exists keep them up-to-date.
This kind of documentation usually provides more value than many javadoc/doxygen generated pages. Nowadays, many people use a wiki software for project documentation. I encourage you to use a powerful wiki like Confluence because it provides rich formatting options and templating allowing for visually pleasing and expressive documentation. As such it may be even printed (to PDF) and handed out to your customers.
- Putting parts like
Installationinto the code repository and integrating them into the wiki often serves administrators, managers (visibility!) and developers. See my older post “centralized project documentation” for some other ideas.
- Wikis allow for easy editing and document sharing and are version controlled. All this facilitates reviews and updates of the documents.
- Document prerequisites and external dependencies explicitly. They may be hard to find in configuration files but are of good use to people running your project.
- Improve searches in the wiki by providing tags and other metadata to help your future me and others finding the information they are looking for.
- Provide consistent examples or even templates for common documentation tasks to encourage others and help them getting their project documentation started.
Good documentation is a real asset and can provide much value if you keep your efforts focused on the important stuff. Complex workflows and draconic rules will hinder documentation efforts wheres open collaboration and valuable documentation will motivate bringing more of it into existence.
One thought on “Documentation for your project: what and how”
There are two major pain problems I have with wikis used as project documentation:
1. I’ve never seen a wiki structured as nicely as a “real” document. Often it’s just a dump of loosely related smaller documents lacking some overall coherency and book-like structure. Have a look at the Flask docs which is a nice example for an outstanding non-wiki documentation  that one could even read sequentially before going to sleep.
2. Wikis are not maintained properly. You mention that they are easy to edit, which is right, but that does not mean that someone is doing it. You also mention, that they are version-controlled, but that happens outside the project and in itself is a mental hurdle. In my opinion, documentation is as important as the code itself and thus should be handled in the same way as code, with proper review and quality assurance which in the end avoids any bit rot.
As an alternative, I much prefer projects like Sphinx  (yes you can use for anything, not just Python) to wikis. The documentation is always with your code, you can integrate it within your development process (e.g. readthedocs.org) and you really have to think about proper structure.
But each to his own, right? 😉