Tag Archives: skill

The Agile Manifesto – Essay 3: Working Software over Comprehensive Documentation

Learn more about transforming people, process and culture with the Real Agility Program

How much documentation does it take to run a project with ten people working for six months?  For some organizations it takes way too much:

Photo of heavy documentation for software project

This binder (about 3 or 4 inches thick) is all the documentation associated with such a project.  In looking carefully at the project, creating the documentation took far more time than the time spent on designing, writing and testing the software.  Yet, the documentation does not produce any value.  Only the software produces value.  The Agile Manifesto, asks us to focus on the outcome (working software) and to make tradeoffs to minimize the means (comprehensive documentation).

The Agile Manifesto asks us to challenge our assumptions about documentation.  In many work environments, documentation is an attempt to address some interesting and important needs:

  • Knowledge sharing among stakeholders and the people working on a project.
  • Knowledge sharing across time as people come in and out of a project.
  • Verification and traceability for contracts or other compliance needs.
  • Decision-making and analysis for business and technical problems.
  • Management oversight and control.
  • Various aspects of individual accountability.

Documentation is usually heavier (more comprehensive) the more the following circumstances exist in an organization:

  • Geographical distribution of people.
  • Lack of trust between people, departments or organizations.
  • Regulated work environments.
  • Depth of management hierarchy.
  • Number of people directly and indirectly involved.
  • Knowledge and skill sets highly segregated between people.
  • Culture of respect for written texts.

Working Software

What if the software itself could address the needs that often documentation is used to address?  Let’s look at them in turn:

  • Knowledge sharing among stakeholders and the people working on a project.
    If the software is functional at all stages, as supported by Agile methods such as Scrum and Extreme Programming, then the software becomes an effective representation of the knowledge of all the people who have participated in building it.
  • Knowledge sharing across time as people come in and out of a project.
    Software that is technically excellent is often easier to understand for people who are new to it.  For example, excellence in user experience and design means new users can get up to speed on software faster.  Use of good design patterns and automated testing allows new developers to understand existing software easily.
  • Verification and traceability for contracts or other compliance needs.
    Test-driven development (code) and specification by example (scripting and code) are forms of traceable, executable documentation that easily stay in-sync with the underlying software system.
  • Decision-making and analysis for business and technical problems.
    In particular, diagrams can help a great deal here.  However, electronic tools for creating such diagrams can be slow and awkward.  Consider the practice of Agile Modelling (basically using a whiteboard and taking photos) as a good alternative to precise technical diagramming if you are doing problem-solving.
  • Management oversight and control.
    Reports and metrics drive much of the traditional documentation in an organization.  Simplifying reports and metrics often leads to a clearer picture of what is going on, reduces the opportunities to “game” the system, and always results in lower levels of documentation.  As well, some reports and metrics can be generated 100% through automated means.  All that said, the fundamental premise in the Agile manifesto is that management should base decisions on what is actually built – the “Working software” by looking at it and using it.
  • Various aspects of individual accountability.
    If you really need this, a good version control system can give you the information for this.  Sign-offs and other types of accountability documentation are typically just waste that doesn’t actually help in process improvement.  Most people who are in high-compliance environments already have licenses and/or security clearances that provide this accountability.  If you software is working, however, then this isn’t even a concern as trust is built and bureaucracy can be reduced.

In my recent training programs as research for this article, I have surveyed over 100 people on one aspect of documentation – code documentation.  Every individual surveyed is either currently coding or has a coding background, and every single person had the same answer to a simple scenario question:

Imagine that you have just joined a new organization and you are about to start working as a software developer.  One of the existing team members comes up to you and introduces himself.  He has with him a piece of paper with a complicated-looking diagram and a full binder that looks to be holding about 250 pages.  He asks you, “you need to get up to speed quickly on our existing system – we’re starting you coding tomorrow – would you prefer to go over the architecture diagram with me or would you prefer to review the detailed specifications and design documents.” He indicates the one-page diagram and the binder respectively.  Which would you prefer?

(I’ve put up a Survey Monkey one-question survey: Code Documentation Preference to extend the reach of this question.  It should take you all of 60 seconds to do it.  I’ll post results when I write the next Agile Manifesto essay in a month or two.)

The fact that everyone answers the same way is interesting.  What is even more interesting to me is that if you think through this scenario, it is actually almost the worst-case scenario where you might want documentation for your developers.  That means that in “better” cases where documentation for developers may not be as urgent or necessary, then the approach of just going to talk with someone is a lot better.

Documentation and Maps

The problem with documentation is the same problem we have with maps: “the map is not the territory” (quote from the wisdom of my father, Garry Berteig).  We sometimes forget this simple idea.  When we look at, say, Google Maps, we always have in the back of our consciousness that the map is just a guide and it is not a guarantee.  We know that if we arrive at a place, we will see the richness of the real world, not the simplified lines and colours of a map.  We don’t consider maps as legally binding contracts (usually).  We use maps to orient ourselves… as we look around at our reality.  We can share directions using maps, but we don’t share purpose or problems with maps.  And finally, maps assume that physical reality is changing relatively slowly (even Google Maps).

Many times when we create documentation in organizations, however, we get confused about the map versus the territory.

Agility and Documentation

Of course, code is a funny thing: all code is documentation too.  The code is not the behaviour.  But in software, code (e.g. Java, ASM, Scheme, Prolog, Python, etc.) is as close as possible to the perfect map.  Software is (mostly) deterministic.  Software (mostly) doesn’t change itself.  Software (mostly) runs in a state absent from in-place human changes to that software.  Software (mostly) runs on a system (virtual or physical) that has stable characteristics.  The code we write is a map.  From this perspective, documentation becomes even less important if we have people that already understand the language(s)/platform(s) deeply.


This essay is a continuation of my series on the Agile Manifesto.  The previous two essays are “Value and Values” and “Individuals and Interactions over Processes and Tools“.

 


Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail

Foundations of Excellence

Learn more about transforming people, process and culture with the Real Agility Program

I was thinking about the concept of becoming excellent at something.  My son is a budding artist.  He and I had a conversation a few months ago about talent or aptitude.  I said to him that I felt that aptitude is only latent: you need to put effort into something in order to expose your talent.  He was concerned that he didn’t have any aptitude because he had to work so hard to become better at drawing.  I compared him to myself and my brother, Alexei: when we were growing up, we both put a lot of effort into drawing.  Quickly, I fell behind my brother in skill.  He clearly had aptitude.  But he also put in a lot of effort into exposing that talent.  I was reminded of all this because my son is struggling with math.  He has aptitude, but he hasn’t put much effort into it.  I was wondering why?

Then I realized that aside from aptitude and effort, two more things need to be in place to achieve excellence: willingness and confirmation.

Willingness is the internal drive, usually motivated by an unconscious set of factors, but sometimes also coming from a strong conscious decision.  Willingness can come from unusual combinations of circumstances.  I was extremely willing to learn mathematics in my youth.  This came from two experiences.  One, in grade 2, was when my teacher told me that I shouldn’t be learning multiplication (my dad had taught me while on a road trip).  I was upset that I shouldn’t be able to learn something.  Then, in grade 3, I had a puppet called Kazir (a gift from my babysitter who told stories about space adventures with Azir and Kazir the Baha’i astronauts).  I brought Kazir to school one day and while doing math problems, I pretended that Kazir was helping me.  Suddenly I found math easy.  These two events plus a few others contributed strongly to my desire, my willingness to learn math.

Confirmation is the set of environmental factors that helps keep us on a path of learning.  These environmental factors are sometimes mimicked in the corporate world with bonuses and gamification, but these are really distant shadows of what confirmation is really about. Confirmation is when the stars align, when everything seems to go right at just the right time, when the spirit inspires and moves you and the world to be, in some way, successful.  The trick about confirmation is that success is not usually about monetary success.  It’s usually about social, relational or even sacrificial success.  As an example, when I was in grade 7, I was chosen with a small group of people in my class to do accelerated math studies.  This was a great honour for me and was a confirmation of my interest in math.

In organizational change, and in particular in changing to an Agile enterprise, we need to be aware that excellence requires that these four factors be in place.  Aptitude is, to some degree, innate.  We can’t trick people to have aptitude.  If someone is just fundamentally bad at a certain thing, despite vigorous educational efforts, then that person likely doesn’t have the aptitude.  Effort is about both having time and resources, but also, then about willingness.  And willingness, in turn, can only be sustained with confirmation.  Too much discouragement will break a person’s willingness.  The Agile enterprise requires a great number of skills and abilities that are not normally part of a person’s work environment prior to attempting to adopt Agile.  Keeping these four things in mind can help people in an organization to reach excellence in Agility.


Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail