News

The Agile Manifesto refers to working software over comprehensive documentation (Agile_Manifesto, 2001). The key to all aspects of the Agile Manifesto, however, is the last statement.

That is, while there is value in the items on the right, we value the items on the left more.

One of the greatest misunderstandings around the Agile Manifesto is the belief in the binary nature of the values. The last statement is critical to understand that there is genuine respect and acknowledgement of the value of the items on the right. The items on the left are considered more important and valuable. In this case, the Agile Manifesto is clear that some documentation is valuable. The tricky part about this, however, is what type and how much documentation is useful? The answer, of course, lies with the team in question. I’ve worked with teams at both ends of the extreme. Teams who say “we don’t do documentation, we’re agile!” to teams who that use overwhelming documentation as a crutch upon which the team leans as a support mechanism. Neither is useful. The key is finding the balance. 

The Kata Approach

Think of this in terms of Toyota Kata.  I’ve used this picture from a blog prepared by Jimmy Janlen, but there are many versions out there (Janlen, 2013).  

The target state in this case or “Definition of Awesome” is that the team prepares documentation that provides value to the organisation.  Some examples of this may be simple user documentation, including help text, support documentation and a lightweight architectural diagram.

The current state may be weighty documentation, heavy up-front architectural design, extensive business requirement documents and a detailed technical specification.

The next target condition may be moving to lighter weight business requirements documentation and lightweight architectural design.  The first steps may be learning to write user stories.  The level of documentation may be somewhat similar, but the first step is moving to writing this iteratively and preparing it at the last responsible moment.  For most organisations, the transformation to an agile way or working is a long journey.  Exceptional results may not be achieved until the target state is met, but the results will steadily improve and that is the point.

A Little More Detail

Let’s now consider the software aspect in a little more detail. Think of software developers as multi-lingual.  People who are proficiently multi-lingual tend to think in the language in which they are currently speaking.  Software developers are the same.  In the event that something goes wrong, or simply a change needs to be made, the first place the developer goes to is the code.  They may refer to the architectural diagram to understand where everything fits in, but I can guarantee that a developer is not going to look at a 200-page document over the code.  In the event that the documentation doesn’t match the code, the production software simply has to be the source of truth.  I regularly ask teams about how often this happens and invariably the answer comes back: “all…the…time”.  I did have one Project Manager say that the documentation ‘had’ to be up to date because their release requirements demanded it.  I asked the question, “How would you know?”

Sometimes documentation simply can’t keep up with production releases. Amazon engineers, for instance, deploy code every 11.7 seconds (Amazon, 2016) . At this rate of deployment, it would be nearly impossible to write detailed documentation for each of these changes.  I am sure that there is some level of documentation for each of these production deployments, but comprehensive documentation would be overwhelming and out of date very quickly.

Each team has to take their first step on the journey from the complex, comprehensive and often out of date documentation processes we currently face.  The team will know the first place to start.  We simply need to provide the guidance and support on the journey.

My Tips

Here are my tips for the first steps on the journey.

Where to start?

1. Look at the most burdensome documentation we are currently preparing and ask ourselves why we are doing it.
2. Review the why and look for the minimal amount of documentation that will achieve the outcome.
3. Consider alternatives to traditional documentation, photos, video walkthroughs and electronic storage and sharing.
4. Invite affected parties such as support teams to showcases, sprint planning, story elaborations and stand-ups.
5. Start again at step 1. 

Post by Julie Wilson

References

Agile_Manifesto. (2001). Agile Manifesto. Retrieved from Agile Manifesto: http://agilemanifesto.org/

Agile_Manifesto_Pinciples. (2001). Agile Manifesto Principles. Retrieved from http://agilemanifesto.org/principles.html

Amazon. (2016). Devops_in_the_Enterprise_Continuous_Deployment. Retrieved from https://www.google.com.au/imgres?imgurl=https://image.slidesharecdn.com/devopsintheenterprise-continuousdeployment-141015150610-conversion-gate01/95/devops-for-the-enterprise-continuous-deployment-9-638.jpg?cb%3D1413516163&imgrefurl=https://www.slideshare

Janlen, J. (2013). Crisp's Blog. Retrieved from https://blog.crisp.se/2013/05/14/jimmyjanlen/improvement-theme-simple-and-practical-toyota-kata