Agile Values: Working Software Over Documentation

Papers everywhere

“Working software over comprehensive documentation”

Of the four agile values, this is probably the least understood and most often misinterpreted. It certainly does not say that there should be no documentation as some (the less ambitious developers and teams) propose. It says that there is more value to actual software than comprehensive documentation.

While I have a great deal of affection for the Agile Manifesto (I believe that dedicating an entire series of blogs to just this particular topic demonstrates this abundantly), I think that the original writers could have been more specific to remove some of the confusion and misinformation that has sprung up around this value. It might have been more appropriate if the original writers would have said, ”Working software over comprehensive requirements and design documentation,” because I think this is more what they meant.

This level of specificity would keep teams from using the excuse that there should be no documentation at all. We have to remember that the writers of the manifesto were doing so as a reaction to what they perceived to be short comings in the prevalent way software was delivered. In that phase—gated approach, copious documentation of requirements and design were produced before any substantive software was developed. Prior to the manifesto, comprehensive documentation could be delivered but working software was either not delivered or poorly delivered because so much emphasis was placed on requirements and design documentation.

In other words, documentation is important but it should be less important than actually building the software. What is the use of great documentation of a system that is poorly or not fully built? Also, documentation tends to be easily outdated so I suspect that the writers of the manifesto were also alluding to this fact. Why create copious amounts of documentation that does not match the final product? Or why spend all our time updating copious documentation as the product changes?

There are usually two types of documentation — internally facing documentation, like design and requirements documents, and externally facing, like user manuals. So far my argument has been for these internally facing documents. Agile addresses these with user stories and acceptance criteria. I like to attack internal documentation using Behavior Driven Development (BDD) since then the code always matches the internal system documentation (see Specification by Example).

What about external documentation? It might be that they would argue that good design would preclude the need for end-user documentation. I suspect the writers of the manifesto would agree since they are user-focused and that they would be more supportive of more of this type of documentation versus internal documentation.

Larry Apke

Also be sure to check out the other post in this series:

Agile Values: The Importance of Individuality

Understanding The Agile Manifesto: A Brief & Bold Guide to Agile – Podcast Now Available

Understanding The Agile Manifesto: A Brief & Bold Guide to Agile by [Apke, Larry]Those of you who may follow this blog may have noticed it has been some time since the last post. It was an eventful summer and it was good to spend some time to catch my breath. Now that the kids are heading back to school, it is time for me to renew my posting. In addition to posting the podcasts, please check back for new Agile posts.

I am pleased to announce that my first book, Understanding the Agile Manifesto: A Brief & Bold Guide to Agile is now available as a podcast. Over the next few days / weeks I will be releasing the book, chapter by chapter, on this website and through the iTunes store under my “Agile Doctor” podcast. Since the book was a series of blogs, the podcasts will also be made available under the original posts.

This project is very dear to my heart as the podcasts were recorded by my son, Vadim Kim, who assisted me over the summer as my intern. I think he did a fantastic job of recording my “little” Agile book and I am sure you will enjoy.

The most recent version of the book includes an Introduction which was never part of any individual post. I have included the podcast of the Introduction below.


Hit Rock Bottom? Maybe Now You’re Ready for Agile


Despair One of the things I enjoy most about my work is meeting other Agile practitioners and coaches and sharing war stories. Recently I was at an Agile Coffee with people who had various experience with Agile, ranging from complete neophytes to folks with many years of experience. The topic chosen was “What are the preconditions for a large company to be successful implementing Agile?” – a very pointed, yet valid, question to be sure. All of the answers were ones that one might expect; support from upper management, learning culture, etc. except for one. The lone unobvious answer was provided by someone whose opinion I respect. I was somewhat surprised at the time and it has reverberated in my mind ever since, “one precondition for a company to be successful in an Agile transformation is they have failed miserably and have hit rock bottom.”

The term “rock bottom” is most commonly used by folks in NA and AA (Narcotics Anonymous and Alcoholics Anonymous). I found the following definition of rock bottom on a website for alcohol addiction:

… often used to describe a point … when they are finally willing to seek help. Things are now so bad for them that it is impossible to deny their problem anymore. Hitting rock bottom may result due to a particular event, or it can be a slow decline over time. This is a subjective term because some … will be willing to suffer a lot more … than others.

I first came in contact with Anonymous groups through my work in healthcare (nearly a lifetime ago when I was a licensed Health Care Administrator) and have more than one commented on how Agile transformations remind me of some of the twelve steps – with the first step being to admit one has a problem.

So when my friend mentioned that a good indicator for agile transformation success was a company had hit rock bottom I knew exactly what he was referring to. In this particular case he used the examples of the FBI Sentinel Project and website debacle. In both cases, it wasn’t until each was a total disaster that Agile was actually tried with any seriousness and rigor and in both cases the results were amazing.

The total spend of these [two] failed [Waterfall] attempts to replace the ACS system was $597m and wasted 10 years. The Agile project, which is now delivering a solution, will only cost $114m for a three-year long project.

DespairIn another recent talk I went to on Agile a gentleman explained how Agile helped with an ad agency. He was only brought in AFTER the agency blew millions on a website that never made it to production. After losing millions I would guess this agency hit “rock bottom”. The good news was that Agile was able to help them to change and allowed them to produce high quality software with a much better time to market (than never).

In my agile coaching practice I have had more than one conversation with enlightened management that has acknowledged our Agile transformation wasn’t working as good as hoped and, barring a complete meltdown, most folks were happy to continue along a non-optimal path. In fact, relative success is a particularly sticky barrier to change as people often confuse the ability to get something done with the ability to get something done optimally. Bill Gates has often remarked, “Success is a lousy teacher. It seduces smart people into thinking they can’t lose.” Sometimes what we mistakenly call “failure” is a much better teacher. Sometimes the lesson is more important than the perception of relative success or failure.

Just this morning I was listening to my local NPR station as they were having a fund drive. Like many others, I couldn’t wait for the drive to be over so I could no longer had to feel the shame and guilt of being a “free rider”. Fortunately, it was the last day of the pledge drive and my mind was only half listening to the chatter of the announcers when they introduced Shankar Vedantam who does segments on the Hidden Brain (which I enjoy immensely). His topic was why people donate (or don’t donate) to pledge drives. He talked about humans’ tendency to pay more attention to emergencies and crisis than what is important. Being the last day of the pledge he hoped what was merely important (donating) would now also be given the status of an emergency because time was running out.

DespairMy mind went immediately back to the concept of “rock bottom” and why this is one good indicator of where Agile can be successful. Sometimes it is only when we hit rock bottom that the importance of being Agile begins to align with the immediate crisis of having to be Agile. It is then, and unfortunately for some, only then when Agile gets the attention and focus it deserves. It is my hope companies realize becoming an Agile organization is essential to their long term survival (at least in organizations that rely heavily on software development), seek the help they need to transition and actually carry out the transition before they hit rock bottom. In the meantime, if you have hit rock bottom (are you listening Yahoo!?), please seek out Agile help.

The 3Ps of Agile Software Development


I am often faced with explaining the various aspects of Agile to people new to Agile and I have come up with a very simple way to remember (and explain) Agile. I present to you now the “3Ps of Agile Software Development” with the hope you find this useful to your own understanding and an aid in your ability to explain Agile to others.


“The world as we have created it is a process of our thinking. It cannot be changed without changing our thinking.” – Albert Einstein

einsteinAt the core of Agile is the Manifesto. A few years back, I even took the time to create business cards that contained the four values and twelve principles. When I heard people say that this is or is not Agile, I could hand them a card and say, “This is Agile.” This is where I start in explaining (and training) Agile because without the philosophical underpinnings one is most certainly lost. I couldn’t give an exact number, but I do know that a high percentage of companies trying to move to Agile are unable to fully embrace and promote the philosophy behind Agile. I wrote my first book, Understanding The Agile Manifesto: A Brief & Bold Guide to Agile, because I have witnessed firsthand the struggle companies are having with adopting the Agile Manifesto. I have seen companies rewrite the Manifesto to omit or change things that they find too difficult to embody and watched good people punished for having the temerity to post the Manifesto at their workplace. The philosophy is the base upon which the other two Ps rest.


“This strange dichotomy, this agonising gulf between the ought and the is, represents the tragic theme of man’s earthly pilgrimage.” – Martin Luther King

martin luther king jr.It is not enough to have the basic philosophical understanding of Agile, we must find ways to embody the principles. There have been a number of ways to embody this philosophy over the years. Take for example, Scrum. Technically it is a framework, but it contains ceremonies (actions) that allow us to realize the Agile philosophy. Why do we do retrospectives? Because the last of the Agile principles state, “At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.” While Scrum has claimed a high level of mindshare, there are numerous other processes and frameworks that also help organizations embody the philosophy of Agile (Kanban, DSDM, Crystal, etc.). In fact, Agile’s history is one of empiricism with people “uncovering better ways of developing software by doing it.” This means it was actually Process (and the 3rd P) which came first. It is Agile Processes that help us to realize the philosophy of Agile.


“Practice does not make perfect. Only perfect practice makes perfect.” – Vince Lombardi

lombardiSometimes when we classify things, people can certainly disagree with our classifications, but when I explain the term “Practices” I am referring specifically to software development practices that are done within the processes and frameworks. It is into this category that I would put things like Extreme Programming (XP) practices as well as something like BDD. What separates these things (which could be argued to be processes) is there more technical nature and the needed expertise of software development professionals (developers and QA) to implement. Processes are things that embody the Agile philosophy which any intelligent individual could understand and facilitate. For example, though it might be optimal for a scrum master to have a development background, one could be successful as a scrum master without it. On the other hand, one could not be successful in performing code review or test driven design (TDD) without knowledge of coding. Why do agilests do BDD? Because through BDD we can realize (among others) the principle that states, “Business people and developers must work together daily throughout the project”. It is Agile software development practices which also help us to realize the underlying Agile philosophy.

While any system of classification subject to interpretation, I have found that speaking to the 3Ps of Agile Software Development has provided a simple and understandable way to introduce people to Agile. If you get a chance to present this, please let me know if it helps you as well.

Project Manager/Scrum Master: A Cry for Agile Help

call for help

Over my time as an Agile Coach I cannot even begin to count the number of times I have been approached by recruiters for a position as a Project Manager/Scrum Master. My coaching colleagues and myself often joke about this particular job title saying, “we like the title Project Manager/Scrum Master because it helps us know which jobs and companies to avoid.” Why would we avoid such positions? For better or worse, by using the title Project Manager/Scrum Master we are able to quickly infer a great deal about the company and their experience with Agile – most of it not positive.

call for helpThe first thing we notice about a company using this title is that they usually have little or no understanding of Agile and Scrum. The duties of a Project Manager and Scrum Master are quite different. Not only do the two roles perform different functions, but they represent a fundamental different in the way they view the world. Project managers in Waterfall try to control projects. Scrum Masters work with Agile Scrum teams to facilitate. In Waterfall, Project Managers have responsibility. Scrum Masters, on the other hand, do not have direct responsibility as the responsibility for success shifts to the development team and Product Owner. Since the Product Owner decides the sequence of the work, a Product Owner is the closest thing to a Project Manager in Scrum. A simple Google search of “project manager versus scrum master” can provide more information on this for those who are curious.

This particular problem manifests when a company desires the potential benefits of Scrum without really understanding Scrum. Without a good understanding, people attempt to map their existing roles with those of Scrum. Let me make one thing perfectly clear. The role of Scrum Master is unique to Scrum and any attempt to map it to existing roles will only result in confusion, frustration and less than optimal outcomes. As coaches, if given the choice of coaching a complete novice as scrum master or “retrofitting” a project manager as a scrum master, we chose the former. It is not that project managers cannot become good scrum masters because many have, but in order to properly train one as a scrum master there is a great deal of work in “unlearning” much of what has been previously trained. With novices the time spent “unlearning” is non-existent.

life perserverThis is why I believe that companies recruiting for Project Managers/Scrum Masters are actually making a very public plea for help. If a company truly wants the benefits of Agile, it is essential that they actually take the time to truly understand that becoming Agile through the use of the Scrum framework is a serious commitment. People must gain a better understanding of software development and how knowledge workers differ, change their fundamental thinking around projects and products, pursue organizational change and realign people around properly configured scrum teams, work with recruiters who understand the difference between project managers and scrum masters and work as partners to recommend better solutions to underlying organizational needs.

For those seeking Project Managers/Scrum Masters, I hear your cries for help. As an Agile Practice Director I would love to help you to better understand your real Agile needs, to help you reorganize your work and people to take advantage of Scrum (other Agile frameworks, methodologies and development techniques), to optimize your organization so that you can deliver high quality software in a shorter time. I am available anytime to provide the help you need. If not me, please reach out to another Agile professional so we can rid the world of Project Manager/Scrum Master for good.

Philosophy Versus Practice

When trying to get waterfall teams and organizations to move to a more Agile development methodology there are two training strategies – philosophy and practice.

The philosophical approach relies on teaching the history of software development and the philosophy behind Agile – the manifesto and principles. This approach assumes that as long as one is equipped with the proper overriding principles then one will be able to make the correct decisions as challenges occur.

The practice strategy relies heavily on training the ceremonies, especially scrum ceremonies like standups, retrospectives, reviews, etc. This approach assumes that if you do the rights things that overtime the reasons for the practices will become apparent.

Continue reading “Philosophy Versus Practice”