The documentation dilemma

During the past few years, IT departments have been shrinking in size without commensurately smaller workloads, and IT managers have had to focus on operational efficiencies to keep things running. At InfoWorld, we’ve been busy with dozens of major projects over the past few years, and one of the things I’ve had to examine is traditional documentation methods for our systems and processes. I’m sure many, if not most, of you share this problem.

Free IT resource Open Source Business Conference (OSBC) May 22-23, 2007 Sponsored by OSBC Free IT resource Virtualization Insights from Top Experts - Learn how virtualization gets real! Sponsored by Dell

When I use the term “traditional documentation,” I’m referring to the finely detailed operational manuals that describe a new system in sufficient enough detail so that any competent IT staffer could operate and debug the system. For IT professionals, traditional documentation often falls into the same category as flossing after every meal or changing furnace filters yearly — it's something you know you should do, but you don’t always get around to doing it.

If you feel guilty about the lack of traditional documentation in your IT organization, you shouldn’t — you might only need to change your approach. Over the past few years, I’ve become an adherent of the Alfred E. Neuman “What, me worry?” school of traditional documentation, because I’ve learned to attack the challenge differently. I realized that with limited staff, a rapidly changing IT environment, and increasing complexity, my own inflexible documentation practices had to be updated to reflect more dynamic environments.

You don’t have to be fully versed in agile software development methodologies to relax a bit and embrace one tenet of the Agile Alliance’s "Manifesto for Agile Software Development": Focus on working software over comprehensive documentation. Although this manifesto focuses specifically on software development, I find that it applies equally well to general IT issues outside of software development. Agile methodologies do not eschew documentation altogether, they just suggest that documentation efforts need only be focused on achieving “good enough” status.

Why is producing and managing traditional documentation a problem for most IT organizations anyway? Aggressive IT project timelines combined with overall IT complexity often leave little time for the level of detailed documentation that is sufficient to debug unforeseen problems within new systems. To complicate matters, many IT professionals abhor writing in the first place, and focused and concise writing is required for clear and useful documentation. Finally, management (that is, people like you and me) tends to talk a big game about the need for documentation while pushing IT staff onto new projects before completed ones are properly documented. An agile documentation process deals with each of these challenges.

While there aren’t a lot of resources for agile documentation available, I did find an excellent essay on the subject from Scott W. Ambler, entitled “Agile Documentation.” You can read Ambler’s complete essay for yourself, but if I could pick the part of his approach that I most identify with, I would choose these sentences: “The best documentation is the simplest that gets the job done. Don’t create a 50-page document when a five-page one will do. Don’t create a five-page document when five bullet points will do. Don’t create an elaborate and intricately detailed diagram when a sketch will do. Don’t repeat information found elsewhere when a reference will do. Write in point form. Document only enough to provide a useful context.”

This is solid guidance for CTOs perpetually concerned about lack of documentation but who don’t want to slow down their IT organizations with cumbersome and counterproductive documentation practices. No one ever got promoted for having comprehensive documentation anyway.