Problem solve Get help with specific problems with your technologies, process and projects.

Is 'Agile software documentation' an oxymoron?

Some software quality pros get the impression picking up Agile means letting go of software documentation, but that's not necessarily so.

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?

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

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.

Dig Deeper on Topics Archive

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.