"My" Agile Documentation
In the last post I discussed agile programming and noted that I was managing documentation development in my projects the "agile way", even though I did not realize I was doing agile. Here I will summarize briefly some of "my" agile documentation principles.
At least do the Software Requirements Specification
I have written about this before - see here and here, so I will not repeat here. Just to recap. I can accept not writing any product documentation, except the SRS. But this one is not optional.
Start with something
I never thought that writing a full, complete, "perfect" document up-front was feasible. It almost never is. Trying to enforce that is futile. It will stress the team members, take an inordinate amount of time and effort and will become increasingly out of date as the project progresses. Soon, large parts of its content will be obsolete, which means (among others) that we have wasted a great deal of time and money.
Instead, start the document with a minimum and flash it out as you go. In the beginning, most everything is fuzzy and changing, hence, write only more general, more high-level things. As the project progresses, more and more things stabilize. update the docs with these things.
Update on the fly
As the project progresses, no need to go into heavyweight documentation cycles. Just update the documents as soon as new information is identified. Any team members can do that at any time. This makes the project dynamic and makes it easier to develop the documents quickly.
Review, approve, disseminate
Documents are useless if nobody uses them regularly. To make them useful you must make sure that what they say is
- Acceptable - make sure the right people review the documentation and ultimately approve it.
- Known - the best document in the world is useless if people don't use it. Most team members will not if you do not distribute the document formally and make sure people use it.
Keep changes at bay
As I noted in previous posts, unlike the agile principle, I do not "welcome" change. I treat change as unavoidable (don't want to say "evil") in the project. So, I know very well that it will come. However, nobody says you must accept it unquestionably. On the contrary, do question the need for any change. If you can avoid the change, all the better. If not, make sure it's reflected in the documentation, especially, if the documents already cover this topic.
Keep the documentation in sync with the code
Ideally, the documentation should drive the code. In reality a lot of changes are decided and implemented in the code without updating the document. This renders the documents obsolete very fast. Get your team into the habit of updating the documentation at the same time they update the code. It's actually easy because if they keep it up to date all the time, the updates are done in many small steps, rather than major update efforts.
Formatting is not critical
I had cases where we did cut-and-paste directly from emails or from comments in code into the document. This creates a rather sloppy-looking document but it's much better than no document at all and often better than spending all that time/money on high-quality tech-writing. The high quality can follow later. Just make sure that the document is understandable, updated and correct.
Solidify as the release approaches
Changes and updates to the documentation should be harder as the release gets closer. If the project is managed properly, this will be natural. If changes continue to arrive in large quantities even as the release is near, something is wrong. To me, it will indicate that the product is immature and unstable. this will prompt me to consider pushing the release date out. on the other hand, if things are done right, the pressure for changes will go down as the release approaches.
But this is not enough. You (project manager) should implement some process that will intentionally make it harder to get new changes in as the release approaches. People should have stronger and stronger justification to incorporate changes as the release approaches.
Instead, concentrate more on changes to the documentation that do not imply changes to the product (code). Corrections and more details are always good. They improve the documentation without requiring changes in the code.
I can probably think of some more but this is a good start and it's getting late...
-----------------------------------------------------------------------------
