We started this season with a focus on satisfying the customer.  Since then, we have built a case for working software being the best way to achieve satisfaction.  Thus, comprehensive documentation is valuable.  However, not as useful to our primary goal.  Agile is often painted as anti-documentation so let’s dig deeper into this comment that could be used as evidence.

…Through this work we have come to value:

Individuals and interactions over processes and tools

Working software over comprehensive documentation

We Value X Over Y

The opening section of this summary says we value all of the listed items.  Rating one over the other does not mean the lesser has no value.  For example, you prefer breathing over food.  Would you argue that food is not essential?  We can take that example further.  You value air over fine cuisine.  Does that mean you do not appreciate food?

It is essential to look at the eight items listed here as critical pieces of a software project.  They are all necessary.  Therefore, we cannot ignore one of them without putting the project in peril.  I feel a need to be clear on this point before moving deeper.

Comprehensive Documentation

Another critical point of this comparison is the idea of comprehensive documentation.  That is a point on which I think we can all agree.  Documentation (of some sort) is required with any software project.  Few would argue against that.  However, “comprehensive documentation” is another level and can be seen as a nice-to-have.  Furthermore, this is a gray area where we could argue what comprehensive documentation contains or encompasses.

Working Software

If “satisfy the customer” is our “why” for a project, then working software is the “how” or the “what.”  We are building an application for our customers.  Falling short of that is the equivalent of “smoke and mirrors.”  Even worse, it could be referred to as vaporware or even a bait-and-switch.  In any case, a customer will not be satisfied until they are at least provided with a product they can use.

We need to tell them how to use it (through documentation), but more value exists in working software.  Even with Agile, we need to keep our focus on the primary goal.

The Twelve Principles and Overall Manifesto

Challenge of The Week: When did you last create comprehensive documentation?

Rob Broadhead

Rob is a founder of, and frequent contributor to, Develpreneur. This includes the Building Better Developers podcast. He is also a lifetime learner as a developer, designer, and manager of software solutions. Rob is the founder of RB Consulting and has managed to author a book about his family experiences and a few about becoming a better developer. In his free time, he stays busy raising five children (although they have grown into adults). When he has a chance to breathe, he is on the ice playing hockey to relax or working on his ballroom dance skills.

Leave a Reply