«    »

Software Documentation Templates

I am a believer in minimizing software documentation that lives outside the code. This does not, however, mean no documentation. There are a number of reasons why documentation can be useful, especially for larger organizations:

  • Documentation is more effective than code at communicating high-level or cross-cutting design and operational concerns.
  • Larger organizations or distributed organizations cannot rely on face-to-face communications or having everyone co-located in one room so documentation has a role to play in knowledge transfer and communication.
  • Documentation can target a non-developer audience, such as business representatives.
  • Documentation helps protect against team turnover, which while a bad practice is not uncommon when using a vendor for development or maintenance or using separate development and maintenance teams.
  • The act of creating documentation helps clarify thinking and identify gaps, thus functioning as a form of quality control.

This last reason is actually quite significant as it is often under-appreciated. In my experience it has happened quite often when I am working on design documentation for a body of code that I identify things that are sub-optimal, such as a badly named class or an unwanted dependency between components. This form of quality control is most valuable, however, when it uncovers gaps such as missing functionality or flawed design. Such gaps are very difficult for most other forms of quality control like testing or reviews to find.

The use of documentation templates makes it much easier to find these gaps by acting essentially as checklists of items to consider. I recently came across a great set of comprehensive templates covering all aspects of software development by Klariti . For a team or organization the price of these templates is ridiculously low - the full set of software development templates costs far less than a day's salary - and there are an assortment of free templates as well.

There are some potential drawbacks to avoid when using documentation templates. Some people have a tendency to want to fill in every section of a template or to use all available templates. This can waste a lot of time and effort. Focusing on identifying what is relevant and useful to document and doing only that is much more effective. Another drawback is that while the templates are in Office format (Word or Excel), you might be better served using a different medium such as a Wiki or a text-based format that is more friendly to version control. In these cases I would convert the templates to the desired medium.

Even if your team or organization has some templates, I think it would be beneficial to check out Klariti's templates and use them as a checklist to see if there is anything missing or needing revision within your own. That link again is: Klariti's software development templates.

If you find this article helpful, please make a donation.

«    »