Write better documentation with four simple steps

To me, documentation is a bit like vacuuming your house. I know it’s a good idea. I also know why it’s a good idea. Yet somehow, it’s still a really daunting task, that I keep postponing until “tomorrow”. So with that in mind, let’s see if I can give a few tips, which can help you write better documentation, while spending less time writing documentation.

Avoid templates (at all cost)

I work in a rather big enterprise organization and boy do they love templates. There is a template for every thinkable document you can write. And there are Standard Operating Procedures (SOP’s) for everything. There is even a SOP on how to write a SOP (I’m not kidding!). However, there are two big flaws with templates:

1. Projects are different, while templates are the same. That makes it hard to capture the nuances, while following the template.
2. The people writing the templates are often not the same as the people using the templates. That means that what is learned while using the templates, is often times lost.

This tip is aimed at “fill-in-templates”. Templates which are more like examples is a different story. You can (and should) use those.

Keep it close

So the enterprise way of doing documentation is to write word documents. And then store them in a document storing system, which was designed back in the 90’s. And then add some random authorizations that is required, to access this document storing system (but make sure that no one know which authorizations). Sounds good? Not really…

Your documentation should be close, to the thing it documenting. Exactly what this means, depends a bit on what you’re working on. But for an open source project, maybe use Github for documentation, since this is most likely where your code is anyway. If it’s a library, make sure to have proper summaries on your public methods (I’m not saying that you shouldn’t document private/internal methods). For end user documentation, built it into your application. Using those mouse-over question marks or just small descriptions under some UI element, describing what it is. No user is ever going to read you 48 pages word document on how to use the application (trust me on this one).

Get inspired by others

When I say get inspired, I actually mean steal. Steal whatever you can. While there are plenty of bad documentation, there are also some good examples. Think of your favourite sources of documentation. Are any of them for something similar to what you are working on? The answer is probably “yes” (otherwise, go read some more documentation). Are you working on a CSS/JavaScript library? Then maybe take a look at the Bootstrap documentation. Or maybe you are working on some extension methods for dates (like I was recently). You can simply borrow the design from the AddDays documentation (AddDays is a .NET extension method for DateTime).

This is not to say that you cannot add your own touch – You definitely should – but there is no reason in starting from scratch.

Make it maintainable

Just like your code, your documentation should change. But just like your code, if it’s one big mess, eventually you (and everyone else working on it) will give up maintaining it. So make sure that your documentation is separated into smaller pieces, that can be changed individually. This will enable you to easily update your documentation, whenever your product changes.