Like many frameworks, the Agile manifesto leaves itself open to interpretation. Essentially, there are four main tenets. In this segment I share my thoughts on the second one: working software over comprehensive documentation. As I’ve discussed in another segment, most organisations I’ve seen go overboard on documentation. So the question becomes, how much documentation is enough?
Fundamentally, time spent documenting delays the development of working software components, either by making developers wait for a product owner or business analyst to create the documentation, or for the team to create it themselves, thereby cannibalising development bandwidth, and throttling throughput. Some defend documentation with an archive value argument, But, at least anecdotally speaking, as with process documentation, it is quite often retained to be able to tick a box and is rarely referenced retrospectively. Add immature knowledge management to the mix, and the value proposition may actually turn negative.
The Agile manifesto addresses comprehensive documentation. The first thing to note is that it does not call for no documentation. Merely comprehensive. This leaves open the questions of what needs to be documented, and how detailed does the documentation need to be. It also leaves open the questions of where to archive the documentation and in what format.
The comprehensive qualifier leaves management with a lot of space to over-index the quantity, as anything less than comprehensive satisfies the letter of the law, as it were. However, I feel that the spirit of the law dictates moderation. And remember, this documentation edict is still balanced with working software, which, as already mentioned, gets traded off in a zero-sum game, as more documentation displaces development and vice versa.
Answering the question of ‘how much documentation’ is still a variable. My intent is not to solve this equation. Rather, it’s to provide a perspective. I suggest that an organisation consider taking a value realisation approach in the form of value stream mapping. Value stream mapping is a Lean process concept that looks for positive and negative value factors. Those steps in a process that contribute to value. Ostensibly, neutral factors are negative factors. As necessary as they will likely be, the goal is to maximise value, and neutral factors do not lead to that end.
I am not going to detail value stream mapping in this segment, but, if you are interested in learning more, I’ll share some references at the end of the written version of this segment. Visit BarcVox.com to find references.
In Agile, an intermediate value is to deliver working software. This is executed in minimum viable product releases. Conceptually, anything detracting from this delivery is either neutral or negative. Although neutral factors are still negatives, they are preferable to actual negatives. Keep in mind that developers are delivering expected value. It becomes a second exercise to compare this against the value actually delivered in the marketplace. This might be an aspect managed by a portfolio theory approach.
Let’s regard documentation. In a perfect world, the product owner would relate to the team what was necessary for the next development cycle, and these features would be rendered perfectly in the next release. I’ll refer to these as sprints, though they are really any such development cycle.
Hopefully, at the start of each sprint, the product owner shares with the team the features expected to be completed in the sprint, and conveys acceptance criteria. S/he would inform the team of any dependencies and challenges. Often, the case is that there are many required features, functions, dependencies and precedences. The functionality will likely be implemented over months or years, so the features need to be documented somewhere. Moreover, these features need to be prioritised in terms of expected value realisation.
Allow me to segue to the topic of value. In many organisations, unlocking value requires foundational elements to be in place. Some of these elements have little or nothing to do with working software. Instead, they involve people, process, and organisation. If a company is implementing a digital commerce solution, it needs data repositories, data management and governance processes, a commerce platform, marketers, and so on. Obviously, communicating with supply chain and inventory processes, payment capture, returns, and the rest. Before you can capture the first drop of value, most of this needs to be in place. Skimping here can limit and delay value capture. In fact, it can affect customer experience and impact loyalty and retention. But that’s not where we’re going to focus our attention in this segment.
If we construct a simple value chain, we start at the customer need for feature functionality, as filtered through the business where it is assessed against current strategic direction and alternative uses of funds. It should be captured in some demand management repository and end up in a backlog. Even if this backlog is Jira, Excel, or Post-It notes on a wall.
Here’s where value stream mapping concepts come into view. If a high value feature is forgotten or unintentionally left on the cutting room floor, you’ve allowed value to remain uncaptured—a cardinal sin of sorts. This is where some documentation retains value and so becomes necessary.
Where else might value leak in this chain. If an item needs to be clarified and leads to a delay in implementation, this is leakage. This might be a use case, some acceptance criteria, a missed test case, or some-such. Of course, these can happen apart from the documentation aspect, but if they are known, they should be captured somewhere.
So, the goal is to capture items that might lead to pauses. This is tempered by over-capture, which might be obvious or redundant information.
Some documentation might be captured in the code itself. This provides guidance and informs the developer in situ. And it provides archival benefit for future code maintenance. This takes a long view, wherein value retention is recognised later. It might prevent value leakage.
In summary, documentation never creates value in an Agile development setting. The best one can hope for is to minimise leakage. As such, the goal is to minimise documentation to the point where the time spent documenting remains less than the time spent clarifying or reworking because the feature request was misunderstood.
I understand that this is a conceptual position to take. No one is likely going to time-test the approaches, but if you can think about this as a mental model for your particular instance, you might find a good defence to promote less—or even more—documentation.
If your only defence is that documentation is contractually obligatory, you might want to bring your attention to the third tenet: customer collaboration over contract negotiation. This would be a good topic for another segment.
References:
- What is Value Stream Mapping by Lucidcharts, a free and paid web-based proprietary platform that allows users to collaborate on drawing, revising and sharing charts and diagrams.
- How to Value Stream Map
- Learning to See: Value Stream Mapping to Add Value and Eliminate MUDA. This book is the original with an exclusive focus on manufacturing processes.
- Value Stream Mapping: How to Visualize Work and Align Leadership for Organizational Transformation. This book provides a perspective on service and office environments.