On the nature of Documentation

Greetings and Salutations,

I found this the other day:

Documentation is like sex: when it is good, it is very, very good;
and when it is bad, it is better than nothing.

— Dick Brandon

So I started thinking about the nature of documentation, and the problem for most of the purely technical and geeky among us is that it does feel like we’re exposed to the dreaded green kryptonite when it comes to writing it.

We all know why it’s important – but in case you don’t here’s a few reasons:

  • Create an accurate record of all systems design, maintenance upkeep, upgrades and configuration changes.
  • Establish history. It’s easier to know where you need to go, if you know where you (or your predecessors) have been.
  • Provide other IS&T staff with a knowledgebase of configuration data, procedures and policies.
  • Ensure consistency through changes and transitions – including staff and the ever present merger/acquisition organisational transitions.
  • It is just good sense.

As always, there will be a few of the readers nodding and saying to themselves, sure, I know, it all makes sense, but who’s got the time?

I understand it, I do, I mean with all of the demands on your time, what with daily production requirements, responding to service requests, dealing with critical projects and the last-minute-sorry-we-didn’t-talk-to-you-when-we-started-the-project-but-we-need-this-in-tomorrow request … documentation is usually delegated to the end of the line.

But it really is a vicious cycle …

If you had meaningful documentation, you wouldn’t spend more time dealing with technical problems. You wouldn’t repeatedly spend your time researching and collecting information that someone in the next cubicle has already collated nor would the team be implementing different flavors of the same technical solutions. It all leads to additional work. In short, it’s all wasted time and effort.

So, the first hurdle, is how you find the time? It comes down to making it a habit.

Every time you start a new project, make sure you include time for documentation. Next time you get called to fix a server that’s gone belly-up, take a notebook with you and write down the steps you took to correct it. New server being built? Write out a step by step as built config doco.

The process here, is to write it down. Don’t worry about structure, language, even if anyone else can make heads or tails of it … this is for you. Once you’ve written these initial notes, you can set aside a few hours a week where you can work on them in more detail.

So, now comes the next hurdle, you need to clearly communicate technical ideas to your audience. Some of these documents will need to be written to technical peers and others to non-technical colleagues (or customers!).

There are literally hundreds of books out there that describe writing styles, documentation projects and documentation best practices.

However, if you only have the time to be “instantly competent” rather than an expert in writing, the a book I was recently made aware of is “Spring into Technical Writing for Engineers and Scientists” by Barry J. Rosenberg. A thorough review is provided by Simon P. Chappell on slashdot.org where he writes:

Unlike most works on literary skills, this book treats you like a geek and realizes that you don’t want to write prose, but you do want to communicate through a written medium.

Might be a good place to start.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s