What’s Down with Agile Documentation?

Recently we worked with an Agile team that was building an FDA-regulated medical device. Some team members were worried about how to produce the required verification and validation documents. “What do we do?” they asked us. “We’re not supposed to do documentation in Agile.”

That’s a myth. In Agile, the question isn’t whether to document. It’s what kind of documentation to create, and when. Like everything else in Agile, those decisions are based on your assessment of value—in this case, the value of the documentation. More documentation is not necessarily better. In fact, the volume of product documentation often is inversely related to its value.

Figure 1: Potential Nonlinear Relationship between Documentation’s Volume and Value

Process Versus Product Documentation

You essentially have two types of documentation: process and product documentation. In either case, we urge teams to focus on the documentation’s consumers and look closely at their usage needs. Look at the documentation from the consumer’s perspective, and explore her usability needs to determine the minimum useful and usable documentation.

Process documentation describes the work-in-progress or handover information the stakeholders produce as they discover and deliver the product—the software application, system, or device containing software. Process documentation has less value for a co-located, domain-savvy team than for a team working in a distributed mode in different time zones and with varying degrees of domain expertise. On the other hand, even a co-located team may need process documentation if it’s building a regulated product and requires evidence of product verification, as in our client’s case. 

Product documentation, which conveys information about the product, is an asset that tends to be valuable because it’s used to sell, service, and use the product. Consider that the consumer of your product documentation might be a validation analyst from a regulatory body, a product end user, an installer, a help desk technician, a field staffer, a maintenance programmer, and so on. 

For our medical device client, the product documentation included scripts for a demo used to conduct validated learning to test the product idea itself. We took the perspective of the people going on-site to conduct the demos, and as a result we created a booklet in a slim, tabular format with abbreviated feature descriptions and demo steps. Not only was this booklet “just enough” to document the product, but also it was fast to produce. As a bonus, the delivery team found the format useful for onboarding new team members. 

On Your Mark…

Teams, including the product owners, need to decide when to produce documentation. There are the two meta-patterns: build it incrementally in small bits as you build the software (and when you have the greatest knowledge for creating the documentation), or defer until prior to release (batching documentation as larger set, created all at once).

When the requirements are fairly well known, documenting early and often makes sense. On the other hand, our medical device client was essentially a start-up. The potentially lifesaving devices were being used experimentally with patients in the hospital, and the requirements were changing as the product itself was being tested. This meant that it would have been wasteful to document what the team was delivering at each iteration. They agreed to wait to document prior to each release throughout the experimental usage of the product (this is roughly equivalent to what a lean start-up calls “validated learning”). For this team, it made sense to defer documentation.

A good practice is to produce documentation as part of the acceptance criteria for completing a slice of the product, whether it’s a story, feature, or minimum marketable feature—whatever anchor you use to describe the requirements you’re delivering. When you make the necessary and sufficient documentation a part of the acceptance criteria, you’re gaining value for little added effort.

Sliding Along the Documentation Levers

Consider documentation formality and precision and the volatility of your requirements. Do you need documentation that conforms to a predefined format, sign-off, and so on? Will informal documentation good enough? How precise must the documentation be? Who will be consuming the documentation, and to what end? And as with our medical team, documenting too soon would have been wasteful because of the volatility of the requirements, and yet when it was produced, it needed to be precise and formal.

There is no one size fits all. As shown in Figure 2, different product and project situations influence how you will adapt your documentation plans.

Figure 2: Adapting Your Document for Different Products

The Low Down on Documentation

Documentation boils down to knowledge transfer. Where possible, document in chunks, and deliver just enough to serve the needs of the specific consumer of the documentation. In that way, you maximize the value you create for the effort you invest.

Don’t forget to leave your comments below.

Reference:
Gottesdiener, Ellen and Mary Gorman. Discover to Deliver: Agile Product Planning and Analysis. EBG Consulting, Inc., 2012.

About the Authors:

Ellen Gottesdiener, Founder and Principal of EBG Consulting, is a leader in the collaborative convergence of requirements + product management + project management. Ellen coaches individuals and teams and facilitates discovery and planning workshops. A Certified Professional Facilitator and a Certified Scrum Master, she writes widely and keynotes and presents worldwide. In addition to co-authoring Discover to Deliver: Agile Product Planning and Analysis, Ellen is author of Requirements by Collaboration and The Software Requirements Memory Jogger.

Mary Gorman, a leader in business analysis and requirements, is Vice President of Quality & Delivery at EBG Consulting. Mary coaches product teams and facilitates discovery workshops, and she trains stakeholders in collaborative practices. She speaks and writes on Agile, business analysis, and project management. A Certified Business Analysis Professional™ and Certified Scrum Master, Mary helped develop the IIBA® Business Analysis Body of Knowledge® and certification exam, and the PMI® business analysis role delineation. Mary is co-author of Discover to Deliver: Agile Product Planning and Analysis.