This post is from the CollabNet VersionOne blog and has not been updated since the original publish date.
What’s Down With Agile Documentation?
Guest post by Ellen Gottesdiener and Mary Gorman of EBG Consulting
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 development, 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.
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 they are building a regulated product and require 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 it was also fast to produce. As a bonus, the delivery team found the format useful for on-boarding 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 a 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; 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.
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!
Gottesdiener, Ellen and Mary Gorman. Discover to Deliver: Agile Product Planning and Analysis. EBG Consulting, Inc., 2012.