… we have come to value … working software over comprehensive documentation…
We don’t do a lot of work with practitioners of agile methodologies. I think that’s partly because there’s some built-in hostility towards documentation in the values of agile development. Of course, while the Agile Manifesto is referring mostly to documentation for the front end of the cycle (i.e., the giant FRS), that hostility ends up spilling over to end-user documentation as well. (I don’t think that was the intention.)
Over the last couple of months, one of my main clients has been moving our documentation processes to an agile methodology in order to align with development processes. It has been interesting, to say the least. The biggest change is the move towards small iterations of documentation that match the iterations of the development process. It means that instead of documenting twenty new features at the end of a three month development cycle, we document a handful of features (or parts of features) every couple of weeks.
What are the challenges?
Get me the code! One of the first challenges we faced was that there wasn’t yet a process in place to get the newest iterations of the applications to me as each iteration of development is completed. This one is a work in progress thus far, but getting the working software iterations to the doc team needs to become part of the process in order to do doc in an agile world.
Get in the conversation. The nice part about the giant FRS is that it’s (often? sometimes?) a great source of information for the end-user documentation. (We’ve converted specs to user manuals and user manuals back to specs, the latter not being a practice we would recommend.) Without the spec, you have a lot more work to figure out just what the application is doing and why. For this specific client, not much has had to change in this respect since I’ve already been able to spend a lot of time with the development honchos, been indoctrinated into their ticket tracker, and have a good background in their apps after several years working with them. Additionally, I’m now working with a great project manager who facilitates my information gathering needs.
Iterations don’t tell the whole story. Each of the iterations we’ve worked on so far has contained parts of features. The most challenging issue so far has been figuring out how to incorporate partially finished features into the overall story of the document as well as how to document the whole story of any given feature when only parts of the feature are complete. One strategy I’ve been using is taking a holistic look at each of the documents I’m working on before each iteration to identify areas that may be affected two or three iterations down the line in a sort of pre-emptive review.
Version control. Simply put, the more times you have to edit a document, the more version control can be an issue. Additionally, with the agile methodologies we have to worry about patching previous versions of the documentation while updates to the newest version are already in progress.
What are the benefits?
Eliminate the big push. The biggest benefit is eliminating the one huge documentation effort for each release. Iterations are quicker and more frequent, but the limited scope makes it easy to get a few changes done at a time.
More review cycles are always better. Of course, each iteration is supposed to come with its own review cycle. I’m willing to bet that some of those review cycles will be missed; however, even if only half of the iterations get a new review cycle, that’s still many more reviews for the documentation than you would get for that one big push.
On the same page. Agile documentation forces the documentation team to be on the same page as the development team. That makes it harder for this or that feature to slip past the documentation team. It also makes it easier for project management since you know just how far along the documentation effort is at any given time.
Get the doc team involved. Documentation folks have a natural affinity to other software related disciplines such QA and UX. How many times do technical writers say “Hey, that doesn’t work quite right” or “Hey, that’s really hard to use” when it’s too late to do anything about it? Getting the documentation folks involved in the development process while the software design is still an evolving thing can help to make the final product a more polished, usable application.