by Alyssa Fox 
Last week I introduced you to agile, an increasingly popular development method primarily used by software companies. This week I'm going to cover how agile helps you get more thorough and timely reviews of your documentation from the team.
Getting Helpful Documentation Reviews
Whether you are in a traditional or agile development environment, getting valuable, informative edits on documentation you send out for review can be like pulling teeth. Some reviewers give the documentation a cursory glance and declare it "okay" with no helpful comments. Others fail to follow the steps as listed in the documentation when testing procedures and have no way to ensure the writer captured everything accurately.
When the Information Development team in my organization used the waterfall process, we used a review cycle that included three drafts of each book: a first draft, an approval draft, and a quality edit draft. The first draft and quality edit draft were internal to our Information Development (ID) department. All of these drafts happened toward the end of a software release cycle and were not reviewed by anyone outside the ID team until the project was feature complete and all features were documented in one fell swoop. Unfortunately, the time when we sent out our approval draft for review by other functional areas often coincided with their busiest times of the release cycle--testing the product and fixing bugs. Because of this poor timing for the documentation review, we often got only superficial edits, or no comments at all, which didn't help us improve the documentation quality.
In agile development, we now write documentation for a feature in the sprint (time-limited development cycle) in which it is developed and tested. For additional information about agile concepts, see Fiona Hanington's article, Can I Be an Agile Technical Communicator When My Team Is Not?.
On more mature products, we no longer send out the entire book as a first draft for ID review. Each time a feature is documented, that documentation must be reviewed by the ID lead/manager and by QE for technical accuracy before the team can close the user story. This idea is similar to a daily in filmmaking--use it to do a quick gut check to see if everything looks okay or if something needs to be redone. We still send out approval drafts for some projects; but for most reviewers, at that point it is simply a director's cut or a chance for them to see the book in its entirety.
Next time, we'll wrap up with how agile helps spread writers' workloads throughout the release cycle.
Note: This article was originally published earlier this year on the TechWhirl website.
Comments