Agile Software Documentation

Like many of the developers I know, I got into this line of work through the back door: I've got an English degree, not a CS or EE or CES or really any C's or E's at all. My MA is in Publication Design, which was at least related: I have designed a lot of web-based publications. But for the most part the writing and design are behind me, and the future is all code, code, code.

...and software documentation. It turns out the writing isn't over, and it never will be. There will always be writing to do in this and any line of work. Hey look: I'm writing now!

So software documentation gives me an opportunity to apply the lessons I've learned over the years. Here are a few of them:

• Understand Your Audience: Before you write anything, you should ask yourself "Who is my audience?" If you don't have an audience, you really don't have any excuse for writing (more on that later). If you know who you are writing for, you can make strong decisions about what to write and how to write it. 
• Write What You Know: This is usually applied to ... well... everything but technical writing. But it turns out that when you're documenting something you don't understand, you're wasting your time. Perhaps in this case it should be re-worded: Understand what you are writing about before you sit down to write about it.
• Be Brief: I've heard this lesson a hundred different ways, but my favorite was from Elements of Style, the de facto standard for writing style: "Omit needless words." An advisor of mine updated that lesson to "Omit words." Don't write more than you really need to.

Getting to the Agile Part

OK, so those are just some general tips for writing of any sort. They certainly apply to software documentation. Where things get really interesting is when you apply those lessons -- as well as some others -- to writing software documentation for an Agile project. For reference, I will turn to an excellent source of guidance on the topic: The Agile Modeling web site. Take some time to browse through the site, paying special attention to their advice on Agile software documentation. I'll include some examples here that essentially re-interpret my advice above:

• Understand Your Audience: Everything you write should be for a specific audience. Yet when it comes down to it, much software documentation is created despite the fact that no one will ever read it! If you are creating documentation because your process requires it, rather than because some very real person will need to read it, then your process is broken. If, on the other hand, you are writing for a real audience, make sure you write exactly what that audience needs (and nothing more). 
• Write What You Know: The hardest part of software documentation is keeping your documentation up to date, and that's specifically because we don't write what we know: we speculate about how a system will be designed, how it will be developed, and how it will operate. In an Agile approach, you document stable systems, not speculative concepts. At the outset of a project you document only what you need in order to make progress with the project. But full documentation of a system before it's even built is futile and foolish: you cannot get it right. Accurate documentation can only be written after development. Otherwise you are writing what you do not know. 
• Be Brief: The goal of agile software documentation is to create documentation that is "just barely good enough." That might sound like weak documentation. But think about it: If you create documentation that is better than "good enough," you have done too much work. If it's not "good enough," you haven't done enough. Don't over-document. Write just enough, and no more. If you have a clear understanding of your audience and your topic, this should come naturally.

It turns out these lessons can and should be applied to any writing you do. My intention here is to promote a smarter approach to software documentation. Software documentation can be burdensome, but it does not need to be. It can be a waste of time, but it does not need to be. It can also be done intelligently, and I think that's what we need in our software documentation more than anything.

Ss.