Most of the documentation I have read over the years sucks. Unfortunately this documentation is an important part of a project[1]. Part of the problem is certainly that writing documentation is something most developers loathe. But there are a few simple patterns which can improve the quality of documentation.

I requested Agile Documentation at work a couple of month ago because I read a positive review about it. Just ignore the ubiquitous “Agile” in the title, more fitting is the subtitle “A Pattern Guide to Producing Lightweight Documents for Software Projects” which is a perfect description for this book. The book contains fifty-something patterns organized in five chapters “Finding the Right Topics”, “Structuring Individual Documents”, “Layout and Typography”, “Infrastructrue and Technical Organisation” and “Management and Quality Assurance”.

In my opinion this is a pretty good ’semi-technical’ book and I can only recommend it to everyone who has to write documentation as part of their job.

[1] I don’t know how many open source projects I have ignored because their online documentation was a mess.