Tag Archives: documentation

Decluttering Photographs: A Scrum Mindset

A common Scrum myth is that Scrum teams don’t keep documents. The many sticky notes on the wall of a scrum room can be anxiety-provoking to traditional suit-and-tie folks. Formal documentation is considered to be the hard product of real work. But the truth is two-fold.

First, Scrum teams do keep documents: The product backlog and the sprint backlog, which are two of Scrum’s artifacts, are key documents for a Scrum project. Each has a precise role in moving the scrum team from product conception to shippable increments. Different teams or organizations keep these artifacts in formats that suit them, but the point is that they do.

Second, it is not true that all formal documents are a faithful (or useful) reflection of work. More often than not, it is not clear what they’re for. Team members typically keep documents in the hundreds, outdated files are seldom deleted and clean versions are often mixed up with drafts. As with all clutter, the 80-20 rule applies rather well here: 20% of documents supports 80% of the work effort. So, 80% of formal documentation is in fact clutter.

Adopting Scrum will challenge organizations to focus on nothing other than completing deliverables of highest value to customers. This focus is in fact reflected by the few but super-useful documents that Scrum teams keep. But to move into this state of razor-sharp focus, we need a clutter-free environment. And while there are many forms of clutter on the job, documents are a big one. Why? Because the documents we keep and the way we use them reflect how well we understand our role. Much like a divinatory tool, the collection of documents you keep are very telling of how you do your work. Is there an orderly process as would be reflected by an orderly and well-organized set of a few focused documents? Or is it a firefighting role as would be reflected by a random set of documents contrived into folders?

Decluttering work documents compares rather precisely with decluttering photographs. Both clutter categories bring up very similar levels of emotional and intellectual charge as well as frustration with the sheer volume that needs to be processed and purged. And unlike the ease of throwing out something bulky like a broken chair or a dulled out piece of clothing, decluttering documents and photographs are very daunting tasks whose detail will bring anyone to tears.

Office documents are very much like a typical photo collection by enthusiastic parents: Several hundred photos of Maxi kicking ball, three dozen photos of the tenth birthday cake, one whole album of Auntie over for dinner, and so on. Photos will range from the incognito-fuzzy to the acceptably crisp. All are equal, however, and are kept in bulging pounds of photo albums or hard drives ranging in the terabytes – or both.

You can see the similarity with documents: Several hundred versions of the scorecard, three dozen presentations on the same topic, a few thousand archive files, and so on. ‘Fuzzy’ documents surely make up the majority. They include the many versions with corrections, inputs and errors, and the older versions to name just a few. The ‘crisper’ documents are typically the most recent ones and likely the ones shared with the VP. But these soon become ‘fuzzy’ as new versions are produced. The main issue with documents is knowing exactly what they’re for and how they support value-adding processes; a problem that doesn’t exist in a Scrum framework.

The main thread of comparison between photos and work documents is the degree of psychic severance that must take place in the mind in order to be capable of throwing out the useless lot. In truth, decluttering photographs is one of the hardest categories to tackle and does not happen until one has built a strong decluttering muscle with simpler categories like clothes, shoes, pots, pans and the like. Because photographs fall under the ‘sentimental’ umbrella, it takes much more than simply assessing functionality. Instead, it requires:

  1. An assimilated understanding of how to declutter, which means having built the decluttering muscle with simpler categories of stuff and having the gut to make sharp decluttering decisions,
  2. A willingness to look squarely at the past and contrast it with today, which basically means grieving and all the complex steps that alone involves, and
  3. A decision about what will be taken into the future, which must be actively considered as opposed to simply assuming that it’s what remains after decluttering the unwanted.

Releasing the way we create, share and keep documents is tantamount to releasing the way we work. That’s why decluttering documents is loaded with anxiety about how the future modus operandi will look like. An additional consideration here is to do this before anything is archived because if all the old is just moved into an archive, no one will open it because everyone subconsciously knows of all the mold that’s growing in there. So better not postpone the pain and roll with the punches. Taking a sword at opening each and every single file and processing for keep-dump-or-change, takes a lot of gut and staying power. Our attachment to documents is quite entrenched but it must be severed for the sake of agility.

The result of genuinely decluttering photographs is astonishing. The grieving process can be very intense; not only are issues resolved and dropped but pieces of the past are recalled into the present and the spirit regains integrity. The past is forgiven and the remains of the day are a powerful collection of sharp moments that are very much alive. Photographs are no longer nostalgic snapshots of the past but evidence of an assimilated experience in effect today. And with that, something very special happens: Fewer and fewer photographs are taken as soaking up a moment becomes far more precious than clunking through photographing it. This vulnerability to the passing of time is a key ingredient for living life intelligently.

Can you draw the parallels with documents? We spend most of our days at work. So, let me invite you to start tackling your collection and see how your newfound awareness pours into every other area of your life.


Affiliated Promotions:

Try our automated online Scrum coach: Scrum Insight - free scores and basic advice, upgrade to get in-depth insight for your team. It takes between 8 and 11 minutes for each team member to fill in the survey, and your results are available immediately. Try it in your next retrospective.

Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail

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

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“.

 


Affiliated Promotions:

Try our automated online Scrum coach: Scrum Insight - free scores and basic advice, upgrade to get in-depth insight for your team. It takes between 8 and 11 minutes for each team member to fill in the survey, and your results are available immediately. Try it in your next retrospective.

Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail

The Agile Manifesto – Essay 1: Value and Values

What is Agile?

In 2001, 17 people got together for a world-changing discussion about software development. They tried to find the common values and principles by which people could do better at the work of software development, which was in a terrible crisis (and still, to some extent is). They were successful in that they created a list of 4 values and 12 principles to guide people trying to find better ways of developing software: the Agile Manifesto was born.

Now, nearly 14 years later, Agile software development has become well-known (if not well-practiced) throughout the business world. In fact, the concepts of Agile software development have been extended through to many other fields as diverse as mining, church management, personal time management, and general corporate management. In the process, there has also been a growing recognition of the relationship between Agile values and principles and those of Lean thinking.

It is time to think about the concepts behind the values and principles. To acknowledge that the Agile Manifesto (for software development) can be re-stated at a much deeper level. To abstract Agile software development to Agile work in general. This is my goal over a series of essays about the Agile Manifesto.

Let’s start with an analysis of the values of the Agile Manifesto in relationship to the concept of “value”.

The Agile Manifesto Values

In the Agile Manifesto we can read the four values:

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Customer collaboration over contract negotiation

Responding to change over following a plan

While a few of these already are quite general, let’s dig a bit deeper by starting with the second value, “working software over comprehensive documentation”. What does this value really refer to? Why do we care about software over documentation. Why “working” vs. “comprehensive”? This is where Lean thinking can help us. The notion of “customer value-added” or just value added work is any work that changes the form, fit or function of that which you are delivering and simultaneously is work that a customer would pay for independently of all the other activities and results you may be spending time on. In this specific example of software and documentation, we can try to imagine what it would be like to say to a potential customer, “we can give you documentation for our software, but we won’t be able to give you the actual software itself… but we’d still like to be paid.” I’m sure it will be clear that it would be a very unusual customer who would agree to such a proposal. Thus, we see that the value of software development activities is in producing the software itself, and the documentation is by necessity of secondary importance.

But what if we are writing a book of fiction? Surely this is documentation! But, it is not. To make the analogy to the type of documentation mentioned in the Agile Manifesto, we would sell a book not just with the story itself, but also with in-depth instructions on how to use a book, how to read, how to interpret our feelings as we read, etc. And not just that, but we would also provide a set of notes to the publisher about exactly how we wrote the book: the time and place of each paragraph written, our original outlines, our research including much that was thrown away, all our conversations with people as we struggled to sort out various plot, character and setting elements, and possibly even all our edits that we had thrown away. This is the documentation to which, by analogy, the Agile Manifesto is referring.

Perhaps now we can look at a connection between the first value and the second value of the Manifesto: that documentation, tools and processes are all much of the same thing. They all belong to the same abstract category, namely, the means used to achieve a particular end. Of course, we all know that both the means and the ends are important, although we may not all agree on their relative importance. Nevertheless, we can probably agree on some extreme outliers that will help us come to the point I wish to make. For example, we can agree that killing someone merely to get to the front of the grocery store line and save a minute or two of time is an extreme case where the end clearly does not justify the means. Likewise, we can also agree that refusing honestly given help out of a desire for independence when it ends with the death of our children by starvation is putting means too much in the fore. Balance is required, therefore. The Agile Manifesto acknowledges this balance by its epilogue to the values, “That is, while there is value in the items on the right, we value the items on the left more.” The other two values of the Agile Manifesto which mention contract negotiation and following a plan are similarly pointing out activities of the means that are non-value added, in Lean terms.

The Agile Manifesto, is stating four values, is, quite directly, pointing to those things which in life are fundamentally of value as ends, not just as means. Individuals and interactions, working software, customer collaboration and responding to change, are all valuable. In order to abstract away from software, then, and create a more general statement of the nature of Agility, we need to explore the idea of value.

The Idea of Value

If we are in business, determining value, while possibly complicated, is not usually too obscure an effort. We look at exchanges of money to see where the “market” agrees there is value. The price of a product or service is only representative of value if someone will actually pay. Therefore, businesses look at return on investment, profit margins and the like to determine value. Similarly, in other types of markets such as the stock market, value is determined by an exchange of money. But underlying this exchange of money is a decision made by an individual human being (or several, or many) to refuse all the other potential uses of that money for the one specific use of making a particular purchase. This choice is based on all sorts of factors. In economics, we talk about these factors mostly in rational selfish terms: what sort of benefit does the purchaser get from the purchase. Factors such as risk, short-term vs. long-term, net present value, trade-offs, etc. certainly can play a role in such decisions. But in business (and in particular marketing and sales), we know that there are also lots of non-rational forces at work in deciding to spend money on a particular something. Value, therefore, has a great deal to do with how a particular person both feels and understands the current proposed “investment” opportunity.

Feeling and understanding arise from many specific factors, as discussed, but what can we say generally about feeling and understanding? They are internal states of a person’s mind (or heart, if you like). Those internal states have been the subject of much discussion in the realm of psychology, sociology, economics, and philosophy. But quite simply, those internal states are greatly determined by perception. How a person perceives a situation is the immediate general factor that determines those internal states. Of course, perception is a general term that includes sensory perception, but also the kinds of prejudices we have, the categories into which we place things conceptually, the internal language we use to describe things, and our existing emotional and mental constructs. So, fundamentally, value is perceived depending on all these perceptual factors.

The Agile Manifesto authors, therefore, had (and perhaps still have) a perception of value which places individuals and interactions, working software, customer collaboration and responding to change all in a position of more value than those other items. But this perception of value may not be in alignment with other people’s perception of value. Still, we can see already in 13 short years that there is broad, if not universal, agreement on these statements of value. Why is this? Why has Agile become so popular over a relatively sustained length of time with a trajectory that still seems to have it growing in popularity for years to come?

Agile values address a deep need in people in the software development discipline and indeed, by analogy, into much of the work world.

In my next essay on the Agile Manifesto, we will take a look in more depth at the first value of the Agile Manifesto: Individuals and Interactions over Processes and Tools.

Some links to commentary on the values of the Agile Manifesto while you wait for my next essay instalment!…

Individuals and interactions over processes and tools – by Mark Layton

Working software over comprehensive documentation – by Renee Troughton

Customer collaboration over contract negotiation – by Jared Richardson

Responding to change over following a plan – by Chris Matts


Affiliated Promotions:

Try our automated online Scrum coach: Scrum Insight - free scores and basic advice, upgrade to get in-depth insight for your team. It takes between 8 and 11 minutes for each team member to fill in the survey, and your results are available immediately. Try it in your next retrospective.

Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail

Agile Guidance Engineering – Applying Agile to Writing Projects

Thanks to Christian Gruber of Geek in a Suite for pointing me to this fascinating use of agile on writing projects: Agile Guidance Engineering.


Affiliated Promotions:

Try our automated online Scrum coach: Scrum Insight - free scores and basic advice, upgrade to get in-depth insight for your team. It takes between 8 and 11 minutes for each team member to fill in the survey, and your results are available immediately. Try it in your next retrospective.

Please share!
Facebooktwittergoogle_plusredditpinterestlinkedinmailFacebooktwittergoogle_plusredditpinterestlinkedinmail