Is 'Agile software documentation' an oxymoron?

Guest Expert Ellen Gottesdiener

Some application developers and software QA pros think Agile software documentation doesn't really exist, or that Agile development methods requires us to shift focus away from documentation. Is that really true?

Requires Free Membership to View

Recently, I worked with an Agile team building a highly regulated product that had stringent requirements for verification and validation documentation. They called me and asked, "What do we do? We're not supposed to do documentation in Agile." That's a myth!

The question isn't whether to document. It's two questions: which is the most valuable kind of documentation for your project and when is best to produce it.

There are two types: process and product documentation. "Process" describes the work-in-progress or handover information you use during discovery and delivery. It's most valuable for distributed teams with varying domain expertise, or when you require evidence of verification.

"Product" documentation is a high-value asset for selling, servicing and using the product. Here, less is usually better. Identify consumers, and focus on their usage needs -- a validation analyst, end user, installer, help desk technician and so on. Explore that user's perspective and needs to define the minimum useful and usable documentation.

The client I mentioned, which builds experimental, life-saving medical devices as part of its teaching and research hospital, needed scripts for a demo being used to conduct validated learning to test the product idea itself. For the people conducting the demos on-site, we designed a slim, tabular booklet with short feature descriptions. It was "just enough" and easy to produce. The team also used it for new team members.

Now let's look at timing. Teams, including product champions, need to ask, "Is it better to deliver the documentation as we build each slice of the product, or to defer and build a larger set just before release?" These are the two meta-patterns.

Consider the volatility of the requirements. For our medical device client, the equipment was being used experimentally with hospital patients, so the specs changed often. Documenting each iteration would have been wasteful, so, during the experimental stage, they documented only before each release.

In other cases, when the requirements are fairly well known, documenting early and often makes sense. You can make it part of the acceptance criteria you define for a product slice -- a story, feature, minimum marketable feature and so on.

Documentation is for knowledge transfer, so you want to document as close as you can to the time when you're creating the product. Document in tiny chunks and deliver just enough to serve the consumer.

About the expert:

Ellen Gottesdiener is founder and principal analyst at EBG Consulting. She has written several books on software requirements, collaboration, and other aspects of the software delivery process. Gottesdiener focuses on Agile methods and proper planning and analysis to improve software quality. She is a certified professional facilitator and a certified Scrum master. She also has ties to the International Institute of Business Analysis (IIBA), where she sits on multiple committees and contributes to various events. In addition to actively working with clients at EBG, Gottesdiener also writes for industry journals, has contributed chapters to various software books and leads training seminars.

This was first published in May 2013

There are Comments. Add yours.

TIP: Want to include a code block in your comment? Use <pre> or <code> tags around the desired text. Ex: <code>insert code</code>

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
Sort by: OldestNewest

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to: