Description
Nearly everyone agrees that good documentation is important to the success of software projects, and yet very few projects actually have good documentation. Even successful projects often have barely adequate documentation.
Often, it’s not for want of effort - the project’s developers have worked hard on it - nor for lack of documentation - the authors have produced a lot of it.
It simply turns out to be not very good - not helpful enough for the users who should be able to rely on it, and a depressing chore for the authors who have to maintain it.
The good news is that both these problems can be solved by understanding how documentation works, and that there are four distinct kinds of documentation - with four distinct functions. The four kinds of documentation are:
- learning-oriented tutorials
- goal-oriented how-to guides
- understanding-oriented discussions
- information-oriented reference material
Structuring documentation according to its four distinct functions helps ensure that each of them is adequately served. It also makes it far easier to write and maintain.
Using real-life examples I’ll draw out the key functions of documentation, and how they map onto different ways of writing it. Putting this into practice is simple when armed with some basic guidelines. The benefits are huge, and available with a minimum of effort.
I won’t be discussing documentation tools or software or other topics that have been covered amply elsewhere, but some neglected and poorly-understood aspects of documentation that will make your software projects and teams more successful.