Welcome back to our Getting Started With Agile series, where we’re diving deep into the underlying values and concepts of the leading agile approaches to help you understand how you can achieve true agility with your teams.
In the last installment, we learned why agile emphasizes the people who comprise your team over the process that they follow.
In this installment, we’ll discuss the importance of delivering working, usable software to your users over simply delivering reams of documentation.
The second value of the agile manifesto stresses the importance of delivering working software to our end users over simply delivering detailed documentation. But why should working software take priority?
To fully understand this, we must first understand what we mean when we say detailed documentation. While documentation can take many forms, such as user guides or manuals, in this context we’re most often referring to the documentation of the technical details of our products. For example, artifacts like detailed architecture diagrams, code documentation, and class diagrams all are great examples of the types of comprehensive documentation that we’re referring to. And although these types of documentation can add value to our product, problems can arise when an emphasis is placed on creating these artifacts over working, usable software.
Illustration by Moe Bonneau.
The primary risk of favoring documentation over working code is that the ideas represented by this documentation are unvalidated until they have actually been realized in code. Therefore, while spending a small amount of time up front to capture and flesh out your ideas for your product architecture can be helpful, investing too much time in capturing those same ideas in beautiful and detailed documentation can prove foolish until you’ve proven that those ideas are actually viable.
Capturing ideas in detailed documentation that later prove to be unviable means that you must either invest additional time and cost into updating that same documentation to better reflect what you have learned, or worse, simply move forward leaving incorrect and misleading documentation in your wake to entrap future maintainers of your software.
But the most sinister problem with investing significant time into creating detailed documentation too early is the realization that this documentation provides no tangible value to your users. Although a client or end user may appreciate the time and effort that you invest in creating aesthetically pleasing and detailed documentation, ultimately they’ll realize that this documentation provides them with little value in comparison to the actual software.
Another danger of this approach is that while the team may appear to be very busy and productive while creating this documentation, they are actually producing no real value while doing so. This can give stakeholders a false impression of a team’s progress since producing this documentation looks like work, but doesn’t realize any significant value.
So if comprehensive documentation is not a reliable indicator of a team’s progress, then what is? Luckily, we already know the answer. The only truly reliable measure of a team’s progress is working and usable software.
Delivering working software allows a team to validate their assumptions of how the code they create will function as well as how their product architecture will perform under regular use.
In addition, working software also is the only way to allow an end user to validate whether or not the product is performing as expected and will truly meet their needs. Regardless of the level of detail of any documentation, demonstrations, or wireframes that are provided to the user, only by allowing that user to get their hands on the software will we know whether or not the team is actually making valuable progress.
In fact, while most high-performing teams consider delivering working software to their users the only true measure of progress, many of those same teams also consider the response of the product’s target market the ultimate indicator of the team’s success. For this reason, these teams begin releasing their product to market at the earliest possible opportunity to accurately measure not only whether they are making progress, but also whether or not they are making progress towards the right goal.
As with all other tenets of the agile manifesto, the phrase “working software over comprehensive documentation” was not meant to convey that documentation had no place in a mature software team’s development process. Documentation can still provide meaningful value to both the team that develops a piece of software as well as to those teams who will ultimately inherit it.
But to maximize the value of documentation, it must be created at the right time and at the right fidelity. Creating documentation too early will often result in extensive efforts to correct and maintain that documentation as the software evolves. Or, at worst, it will simply result in incorrect and misleading documentation that no longer accurately represents the software’s intent or construction.
To remedy this, teams must learn to strike a balance between creating high-fidelity documentation that can act as an accurate source of information for the future but become unwieldy to maintain in the face of a changing system, and low-fidelity documentation that can be created and maintained easily but yields little value when it’s needed.
However, even with the advantages that documentation can potentially add to the future maintenance of a product, teams must always remember that the true value that they create—and the most accurate measure of how they are creating that value—will always be working and usable software.
Jeremy Jarrell is an agile coach who helps teams get better at doing what they love. When he’s not mentoring Scrum Masters or Product Owners, Jeremy loves to write on all things agile. You can read more of his thoughts at www.jeremyjarrell.com, see his videos at Pluralsight, or follow him on Twitter @jeremyjarrell.
Category: Productivity
