Right-sizing Documentation in an Agile World

Within an Agile context, there is a focus on right-sizing documentation.  This is a response to the bureaucracy that has led to large volumes of project and product documents which are often left unread, are out-of-date the moment they are complete, and seem to have little value to the team.   On the other hand, I have heard folks who are in an Agile context say that no documentation is needed.  The truth is somewhere in between.    

One of the values in Agile is “working software over comprehensive documentation”.  This does not mean that there is no value to the item on the right, but there is more value to the item on the left.  The key is right-sizing the documentation.  Right-sizing means that the level of effort applied to write and maintain the documentation plus the value of that written document should have a greater return on investment (ROI) then not having that information readily available (i.e., the effort it would take reconstruct the information and impact of not having that information for current decisions).   With that in mind, here is some high-level guidance on right-sizing documentation. 

• Documentation should be living and evolutionary and not “sitting on the shelf”.   Move away from the notion that document is “final”.
• Consider some documentation to live at the product level where it may naturally evolve from both sprint to sprint and from release to release. 
• Documentation should take on a collaborative nature.  It should not be written by one person to perfection, and then shared with others.  It should instead be shared often during draft to gain input   
• Update your documentation continuously as new things are learned.  If you learn something that can impact the team or help with decision-making, go to the document and update it. 
• Focus on just barely good enough documentation and avoid big upfront details which typically means a lot of guessing and wasted time.   Barely good enough means document what you currently know.  If you no longer need the document, it is reasonable to retire it. 
• Be concise and lean.  Write in succinct prose and add bullet points if reasonable.  Avoid long and flowing prose which may lose the reader’s attention.
• Documentation can take many forms.  It is not only a Word document, documentation can live on a wiki, in the Agile planning tool, as comments in code, and much more
• Document decisions.  Knowing the decisions helps those who must maintain the product and understand why things were decided or done in a certain way.   
• Realize that there is a difference between internal and external documentation.  External documents may be a User Guide or document that gets delivered to the customer.  These should be considered as “working software” and follow the rules of the done criteria.    

What might get documented in an Agile world?  The major documentation comes in the forms of user stories and epics.  This includes writing the user story in canonical form, with details, and acceptance criteria.  Technically, another significant form of documentation is the code itself. It should be written in team agreed coding standards with appropriate comments that specify what the code does (or simply and clearly enough that don't need explanation) and why it was written a certain why.  Remember that code needs to be maintained so if someone has to "figure out" what you wrote and why in order to support the code, then it is problematic.

You should consider lean versions of your architecture, coding, and test strategies that help inform the team of ways of working. Impediments that require effort to fix should be documented.  Items such as coding standards, an overview of your working processes and policies, done criteria such also be documented and shared. 

What do you think of this guidance?  Do they make sense?  Do you have any other tips?

A Path from Command and Control to Agility

Have you ever noticed a team where little engagement, a lack of ownership, and team decisions are scarce?  One reason could be the amount of command-and-control from management that is occurring.  Often times this is one of those unspoken elephants in the middle of the room.   Command-and-control bosses and leaders are a sure way to kill the feeling of ownership, engagement, and empowerment in team members. 

Agile comes along and promotes self-organizing teams, transparency, and team decision-making.  It also helps companies bring more value to customers and adapt to the market conditions, ultimately leading to making more money.  Within an Agile culture, it no longer requires a manager to tell a team what to do.  The number of organizations following Agile continues to increase. They realize that they no longer need directive managers but leaders who act more as coach and mentor, then the traditional boss.  So what is a command-and-control manager to do?   

• If they feel they have command-and-control traits and are willing to make that move to Agile, they can test their comfort level with collaboration first.  When a team decision is needed, consider an experiment.  Ask the team for their thoughts.  See if the command-and-control manager can be just one voice of the many that are on the team instead of forcing a direction.  Better yet, see if the manger can remain quiet and let the team arrive at a decision.  If this works, next they can test their comfort level with self-organizing teams.  The next time there is a decision that impacts the team, ask they can ask the team to discuss it amongst themselves and decide the course of action.  Stand back and let them decide. 

• If the manager is inquisitive about Agile, provide them some education on the Agile values and principles.  They should consider what they think each of the principles mean and if they believe in them.  A bolder move is having them share the Agile principles with their team and ask them what they think it means.  Also they can ask the team members how it can be exhibited on a team.  Ask the team members if they think we would be a good idea to exercise some of the principles. 

• If they have directive tendency and their current role has them interacting with customers to understand customer needs, then they may consider becoming a Product Owner (PO) for the team.  While they should no longer be manager, a PO helps shape the product through the collection and grooming of the requirements.  The PO also shares the need with team members during the Agile-related planning events (e.g., Sprint Planning).   

• Learn about the concept of bounded authority.  This is where the team can make their own decisions, organize, and commit to their own work.  It does not mean that teams can do whatever they want.  The balance is that the manager keeps limited responsibilities to provide vision and support for their staff while allowing the team the ownership to self-organize around the work.  

So I will leave you with this question.  Which approach will lead to more productive and high-performing teams?   Is it a culture where managers tell employees what to do or is it a culture where employees are self-organizing, feel ownership of the work, and are able to use much more brain power?   If managers exhibit command-and-control tendencies, it is in their best interest in the long run to adapt toward and Agile mindset and allow for self-organizing teams.  Since Agile is pervasive in many companies, it is an opportunity to adapt and help the organization toward better business results.