Effective documentation

In most software projects there is some requirement for documentation. In the few projects where there are no specific requirements it is a matter of good craftsmanship to determine just the right amount of documentation to deliver. At a minimum, it should be enough to enable another person to deploy and maintain the delivered software.

Three types of documentation I encounter the most are requirement specifications, technical designs and source code. Though I find it crucial that source code is well documented in order to maintain it properly, this post is about the external types of documentation (from the source code perspective). Browsing through source code is very time consuming. How can we write good external documentation to enable project members to quickly learn about scope, design considerations, accidental complexity and other important functional and architectural decisions?

Functional requirements

I exclusively work in agile environments. Shorter development cycles, instant feedback and iterative thinking require a different requirements process than the traditional waterfall approach. This also leads to different kinds of requirement specifications. Requirements are more and more captured in separate use case documents or stories, instead of being lengthy, hard to read documents.

In some cases however, requirements may need some form of background documentation. Consider for example a case where several functional options are explored and weighted in great detail. It can be very helpful to document these options and the decision making process for future reference.


Technical designs
For technical design documentation this is even more important. During the lifetime of a project lots of technical decisions are being made. For most technical decisions several options are explored. It is a huge waste of knowledge if these options are not documented. When new developers are added to a project I am often asked why a particular approach has been taken. Having a correct amount of documentation available does not only clearly show pros and cons for every option, It can also lead to new insights, because the reader is actively going through the reasoning process, instead of reading outcomes.

example of a classical technical design: lots of text and concepts spread over multiple pages....

Guidelines
So how to put all this information into a single document, that is still readable? In my experience, the accidental complexity of the document structure limits the allowed complexity of the documented subject. So I keep the structure as simple as possible.

maximize value
Every page must be self-explanatory. This forces the writer to be short and precise. It also provides an immediate overview of the scope and does not force the reader to browse through pages, getting out of flow. Single pages can be used for reference and taken to meetings to support conversation.

define scope

Every page covers no more than a single topic. Adding more, increases document complexity and might unnecessarily confuse the reader. If a topic is too complex to fit on a single page, I split it up in simpler concepts, or use different view levels. 

document the process

When there are multiple solutions to a problem, all considered options are described on a single page with a short analysis of each option and a judgement of important aspects. This documents earlier considerations and allows for a better general understanding of why a specific option was chosen.

be concice

A picture is worth a thousand words. It gives immediate overview and can hold large amounts of data. I try to capture every topic into a single image, using up most of a page's real estate. I add a notes section on a page to provide some context or explanation that does not go very well into the main image.

appeal to the reader

The reader has to absorb a lot of information. I always make sure that every page is visually appealing and requires little reading to keep the reader inspired and focussed, instead of easily distracted.

use proper tooling

I prefer to use graphical tools over word processors, because they allow for more creative freedom.

invest in writing

Most documents are written once, updated regularly and read often, so I spent quite some time optimizing for reading at the cost of writing speed.

write together... and enjoy!

Writing documentation should be fun. A solid foundation is the best incentive to construct a high quality document to which everyone in a team can contribute.

example of a visually appealing design that weights various options to solve a specific problem

Getting started

As a starting point I used some templates available at http://www.visualspec.org/. They can be downloaded or serve as  a source of inspiration to build your own.