Way of the Retainer

I’m going to be unfashionable for a moment. And, I swear, I’m not being unfashionable to be fashionable, despite being a grunge child.

My name is Kevin Powe, and I enjoy writing documentation.

There. I said it. I’m in the process of producing some documents around architecture/development process for a client at the moment, as well as documenting some software we use internally to the company, and I’ve been reminded of the benefits of writing documentation.

I’ve never found a better mechanism for forcing out the fine details of something than having to explain it. Whether its through delivering training, or talking to a co-worker, or, in the dim dark past, getting involved in long Usenet rants. It forces you to take an instinctive understanding of something – the 80% that’s good enough to get you going, and flush out the mystery in that last 20%, where surprises and magic often lie.

Also, it could just be that I’m a giant dork, but I find that there’s this amazing fractal effect that occurs as well, where you realise the minute detail encompassed by broad generalisations or summaries. “Oh, and to get to Mordor, you have to do A, B, and C. And to do A, you have to do X, Y and Z in order.” It’s part of one of the reasons why I love software development. Most coders I know who get involved in a new domain of knowledge (Sudoku, learning French, Minesweeper) write programs as a way of understanding the domain more deeply. A computer assumes nothing, so you have to tell it everything. And that level of detail, explicit understanding rather than implicit, is a fine Tanelorn to reach for when writing documentation.

The other thing I’ve always found documentation great for is is highlighting inefficiencies, or the possibility for enhancement. You may have gone through three screens of input to create a new purchase order every time you tested functionality without thinking, but once you start explaining to the user through documentation that they have to go through those three screens, you realise it’s going to be even more of a pain in the arse for them to do than it is for you to document.

And that brings me to the final coffee-enhanced peace-love-and-mungbean part of what I’m saying:

Good documentation is how you communicate with someone out there, that you’re fundamentally solving a problem for.

Bad documentation? Well, that’s a whole ‘nother kettle of fish

No Comments »