One of the value statements mentioned in Agile manifesto is as follows

Working Software over Comprehensive Documentation.

During my interaction with different teams of varied experience level in agile, I observed that teams tend to interpret this statement as Working software is the only thing that matters in agile and any other documentation other than a set of user stories is a waste. Having different interpretations of a statement isn’t new to us, similar things have happened in our world with the holy books of different religions too where the verses mentioned in the books are interpreted in different ways by different people.

In this post, we examine the value statement by using sample product cases to help us arrive at a decision on the level/types of documentation that might be needed to maintain the product.

Sample list of documents in Software Development

For simplicity sake let’s bundle up documents into 3 categories i.e. Fly-weight, Medium-Weight and Heavy-Weight. The categorization helps in making the response a bit concise in this example.

Note: The above list is not comprehensive and is only a suggestive list. Please do not start a documentation war on the post for this. In reality you should choose what is best for your team and the product.

Cynefin Framework 

Few years back I read about Cynefin (pronounced ku-nev-in) framework which is developed by David J Snowden while he was working with IBM. Cynefin framework is a decision-making framework that can help us make better decisions based on the context of the problem.

The framework sorts the issues facing leaders into five contexts defined by the nature of the relationship between cause and effect. Four of these the simple, complicated, complex, and chaotic require leaders to diagnose situations and to act in contextually appropriate ways. The fifth disorder applies when it is unclear which of the other four contexts is predominant.

Image credits : By Snowden - File:Cynefin framework Feb 2011.jpeg, CC BY 3.0, https://commons.wikimedia.org/w/index.php?curid=53504988

I recommend reading this article https://hbr.org/2007/11/a-leaders-framework-for-decision-making by David J. Snowden and Mary E. Boone if you aren’t aware of the framework.

Define Problem Context

To define the problem context, we are going to consider 3 types of products and our aim here would be to respond with the category of documentation that may be needed for the product.

Our sample products

1. A Martial Arts Schools wants to build a website to allow students to register for classes and display calendar of events for the year. A team of 6-9 motivated team members is selected to build the website.
2. A Financial firm wants to build an internal product that will allow creation and processing of trades with daily calculations followed by reporting of accurate information to the business teams within the firm. This product will be developed by 3 teams around the globe with each team having around 6-9 energetic team members.
3. A Medical firm product wants to build a product which will interact with human body through sensors to display the information related to weight, muscle strength, body fat index and suggest a diet along with exercise routines. This product will be used by customers all around the world in their gyms and to build this product 4 teams have been set-up with each team having around 6-9 positively motivated team members.

Apply the Cynefin Framework

We are now ready with our problem context and possible responses, let’s apply the problem context in Cynefin framework

Simple Contexts : The domain of Best Practice

Martial Arts School Website

The features requested are common in today’s world and the site is developed by 1 single team, the truck factor of such teams will usually be on the higher side. Therefore, I am more eager to categorize this in Simple context. For documentation needs, I will choose the fly-weight category.

Complicated Contexts : The domain of Experts

A Medical firms product

The features requested interacts with human body through sensor. Further it may have to analyse the immense amount of data passed by the sensor to come up with valuable suggestions. Such software will undergo stringent tests and would require some upfront planning along with comprehensive documentation including a user manual. To develop such a product, the team will be consisting of medical and hardware experts. Therefore, truck factor of such teams will be very low, so preserving organisational memory is of utmost importance for the success and survival of the product.

I would therefore choose to categorize this in the Complicated domain and would select the heavy-weight category for documentation needs.

Complex Context :  The domain of Emergence

A Financial firms product

The features requested here may be common to the financial industry but each organisation have their own unique way of creating, processing, storing and analyzing the data. To develop these features, you may require specialist team members in your team such as Business Analyst, Technical, and/or solution Architects. The truck factor for such teams might be low due to involvement of specialists so preserving the organisational memory is of importance for the success and survival of the product, however this being an internal product we may not necessarily require a detailed user manual and hardware specifications/diagrams.

I would therefore choose to categorize this in the Complex domain and would select the medium-weight category for documentation needs.

Chaotic Contexts : The domain of Rapid Response

If we get a production issue in any of the 3 products, then in such case, the top most priority will be to fix the issue or stabilize the situation quickly and then move to the products domain context.

Responses

To summarize

• For Martial Arts School Website we can use fly-weight category of documents.
• For the Financial firm’s product, we can use medium-weight category of documents.
• For the Medical firm’s product, we can use heavy-weight category of documents.
• For any urgent issues related in any of the 3 products mentioned above where cause and effect are not clear, the response in such situation will be to fix the issue or take any necessary action to stabilize the issue and then think about any documentation that may be needed for future reference and knowledge base.

Ways to reduce excessive documentation needs

• Update the document when the change is stabilized: The documents listed in the fly-weight category should be created and maintained continuously along with the product increments. Once your product increment has been reviewed by the stakeholders, then the teams in complex and complicated domain can choose to update their rough designs in the detailed documents such as Technical Architecture, Business Process and Model diagrams etc. By delaying the updates, we are just trying to minimize the rework efforts that may be involved should the stakeholders ask for changes which disturbs the architecture of your product in a significant way. That being said, teams should not take this as an advice to have an iteration that is specific to only documentation tasks.
  
• Improve collaboration and increase the Bus/truck factor of your team.
  

Lastly, I’d like to remind ourselves that however important the documentation part may be for the products and for organisational memory, ultimately it is the product that sells in the market, it is the product that competes in the market and generates revenues for our customers. Therefore, any significant documentation efforts involved should be agreed with the stakeholders.

I am hopeful that I achieved some success in explaining the varied needs of documentation in agile through the above examples. Working software is the primary measure of progress however in order to sustain the product, we may have to produce knowledge base which lives with the product for its life time. The comprehensiveness of this knowledge base depends on the products complexity.

Reference

http://agilemanifesto.org/

https://en.wikipedia.org/wiki/Organizational_memory

https://hbr.org/2007/11/a-leaders-framework-for-decision-making

https://en.wikipedia.org/wiki/Bus_factor

http://agilemodeling.com/essays/agileDocumentation.htm

https://en.m.wikipedia.org/wiki/Cynefin_framework