Software Documentation the Agile Way

While doing research for a client, I came across a very interesting paper entitled “Efficient Authoring of Software Documentation Using RaPiD7.”

Agile practices generally encourage using automated test suites as living documentation for a system under development. Agile says do the least amount of static documentation that will work because it will invariably diverge from reality and quickly become useless. How many thick software documents have you seen sitting on a shelf doing no one any good and existing entirely out of date? Exactly.

Still, because of corporate, regulatory, or other factors, extensive, formal software documentation is often times required. In these cases, these documents are best thought of as a product to be delivered along with the software itself. So, how do we do documentation in a smart, effective, Agile way?

RaPiD7 was developed within Nokia in the 2002-2003 timeframe. The motivation is clear… make documents that match reality and create them with as little effort as possible. It seems to me that the RaPiD7 approach itself embraces two very Agile practices: Whole Team & Do the Simplest Thing That Will Work.

You can read the paper to learn the nuances of the whole process (download for a fee here). But the key ideas are these:

1. Wait as long as possible (so the eventual document matches reality).
2. At each documentation delivery point (be it a milestone or final delivery), assemble all the project stakeholders for a workshop.
3. In this workshop (perhaps a half or whole day), collectively create the necessary document outline and then write all of the sections in rough draft form concurrently. With everyone assembled, questions can be quickly answered and the energy of the event carries writing through to the end.
4. Assign one person as THE EDITOR.
5. THE EDITOR assembles all the sections written in (4), proof reads, gives the document a consistent voice, and communicates with the workshop members to clarify any remaining points.

I was struck with the genius of this approach. I’m actually looking forward to an onerous formal documentation deliverable just to try this out.