In my last post I looked at the Processes and Tools side of the first line of the Agile Manifesto. This time I’d like to look at the second line – Working Software over Comprehensive Documentation.
In many projects I’ve been on just getting any focus on Working Software was a challenge, and by “Working” I mean actually delivered production capability, there is a reasonable argument to change the manifesto to “Working software over everything else” and leave it at that!
But assuming that we are in a situation where we are delivering production quality every sprint and at least on a fairly frequent basis (2-4 sprints) that work is actually being deployed to production, then we can turn to the documentation and ask, so how much is needed and why is there a perception that Documentation is bad?
Firstly I’d like to split all documentation into two camps:
- Documentation which is an end in its own right
- Documentation which is a means to an end
Practically speaking any document that you are going to need after the project is in the first camp, and everything else falls in the second. I’d like to make the general sweeping statement that the first camp is useful and should be perceived as project deliverables, the latter should be minimised. As an author of something, ask yourself whether anyone will ever read it after you go live – if not, then you are in the second camp.
Examples of documentation which is a means to an end would be user manuals, API service catalogues and training guides. These typically provide explanation as to how the application or its components function so that once the project development team have moved off others can understand how to use it, reuse parts of it or change it.
Some of these can be expressed in terms of a User story: As an application support user I need an explanation of the system architecture so I know where to investigate should an issue arise. The problem with expressing them like this is obselence, once you have delivered the story, and then the application changes – the document is obsolete. Typically these needs should be identified up front and then worked into the Definition of Done, so if you know there is a need to have a user manual – then updating the master document for each delivered User Story during the sprint will ensure that you always have correct documentation and don’t get into the horrible situation of having to balance the needs of delivering functions or enabling the users to understand the ones they already have.
Now most project documentation doesn’t fall into this group – most of this group would be considered optional (aspirational even) and often is outsourced to a separate group under Change management, desperately trying to catch up. Most project documentation I would argue is about gaining understanding of what we are doing now or how we have done – and really much of it is a waste of time. Here we have Requirements, roadmaps, “Strategies” of all types such as Test Strategy or Comms Strategy and progress reports. Each of these hold no value in their own right, they are only a means to an end, typically successful delivery of the project.
Approach these from the perspective of their purpose rather than their form, templates for example are there to make your life easier to ensure nothing important gets forgotten – more often though they are treated as a ruleset and create additional work. Create the document purely against it’s function, so a feature requirement is usually to enable the team to understand what is needed and have something referenceable for acceptance criteria during development – so really a few notes scribbled on the back of a credit card bill pinned to a wall may achieve that. A Strategy in this context is usually just a set of ways of working, that should be flexible anyway – so a few “agreed principles” posted to your wall should suffice.
There is a big difference in documentation between Waterfall and Agile and it relates to the level of collaboration between work definition and work delivery. Under a waterfall framework the people defining the work may do so far in advance of those delivering it, and may not ever meet – under these situations the “Purpose” of the document is similar but it also has to stand alone, unsupported by the day to day working relationship between the author and the developer, and as such needs to be a lot more thorough and structured. An Agile approach enables the level of detail and structure to be reduced to only what is necessary to get the developer to the end of the sprint when the author is sitting only a couple of metres away.
Also Waterfall derisks through total understanding of what we intend to do and how far we are through it, Agile derisks through delivery, so progress reports are only of interest for the current (small delivery) and the risk they look to manage is similarly much smaller.
I often hear that organisations require their user stories to be fully comprehensive, because those Stories are used as long standing artefacts for application support to reference, or for the training dept to use to create their guides. This is a very messy and inefficient way of operating for a few reasons. The User Stories are not easily referenced, they are usually organised against sprint not current application feature and it is common that no single user story defines any one page or process in the application due to the number of iterations that it has undergone. User stories are written to enable the team to be able to deliver them, they aren’t written with an abstracted Application Support user in mind. This results in over specified stories wasting team time and still leaves the “other” consumers with a headache in trying to find the information they need. It often occurs if the business processes around implementation haven’t been considered at the outset – so the project is probably still clinging to waterfall practices for implementation. It is better that the team just creates what is actually NEEDED as they go along – and keep their requirements for themselves and suitably lean.
In Summary:
- Try to build useful long standing documents into your Definition of Done
- Documents that are internal to delivery should be written for their purpose only and time spent polishing them is a waste. Remember, only the USE of the document has any value – intrinsically it is worthless.
philagiledesign 