“Working Software” – Agile Development II

In this post, we will explore two products of Agile Software development teams—working software and its complementary documentation—to determine which is more valuable and therefore which deserves the team’s priority and focus.

The second core value of the Manifesto for Agile Software Development states: “… we have come to value: working software over comprehensive documentation.

comic- working software
comic- working software


That is to say, software is the priority and should be written first.  Wow! Does this statement defy all common convention when it comes to reviewing exhaustive requirements lists and producing countless reams of design documents for seemingly infinite rounds of reviews before a single line of code is written? Yes and no. Let’s review.

Yes: the idea that software is more valuable than its documentation and therefore code should be written first is absolutely contrary to what typically happens in software development shops. Many software developers are still asked to create documents that explain their thought processes throughout a project. Agilists suggest producing a lot of documentation upfront may delay value delivery to the customer; may risk rework should things change; may hinder the discovery of design flaws; and may yield a lot of waste should complex features go unused. Writing code first and producing documentation as needed is definitely a risky proposition.

No: the Agilist’s value proposition is not quite as radical as it may sound. Despite the preference of software over documentation, it does not mean developers shouldn’t produce any documentation. It just means they shouldn’t produce comprehensive volumes of it. Documentation is, in fact, a valuable tool for planning and communication. But documentation should be a secondary priority to software and should be produced sparingly. Agilists suggest developers document “just barely enough” to effectively communicate amongst their team and to their successors.

In the mobile app development space, this Agile philosophy of a value-driven approach to software development is very practical. Mobile development teams are often smaller with fewer communication channels. Therefore, not as much documentation is needed. Additionally, the compile-times for mobile apps are often far shorter than their server-based predecessors, so frequent delivery of working software to the customer is certainly possible.

From the software developer’s perspective, the preference for writing code over documentation seems obvious. After all, they don’t consider themselves documentation developers! So of course they’d rather be writing code. More importantly, what does the customer value more—working software or comprehensive documentation?

We can all answer that question. Think about the last time you bought an app, mobile device or home appliance. Did you first read the user guide? Did you even look at the documentation?

Obviously, most customers will value software over its documentation—as long as it works. The Agilists very deliberately specify working software in their value proposition. If it is broken or does not behave as expected, it is not very useful or valuable to the customer.

The “working part of “working software implies the customer has clearly communicated his expectations in the form of a use-case, acceptance test, checklist, or any other “definition of done.” As long as the software product meets criteria set by the customer, it is safe to say it is more valuable than its documentation. And the most effective way for the customer to judge how well those expectations have been met is by using the software, not by reviewing a document.

Whether a developer or customer, we can all agree the Agilists have their priorities straight. Working software is more valuable than comprehensive documentation. Therefore, Agile teams should write code first and then document as needed. They should deliver working software often and their progress is best measured by using the software. This represents a shift in the traditional software development paradigm and is best suited, perhaps, for the latest genre of software development—mobile apps.

Share on

linkedin sharing button twitter sharing button