Documentation IS Important in Scrum

As part of the Manifesto of Agile Software Development, to which scrum is an adherent, there is a list of things which are valued.  These valued things include "Working products over comprehensive documentation"  The manifesto goes on to say, "That is, while there is value in the items on the right [processes and tools] we value the items on the left [individuals and interactions] more".

I've heard this principle expressed in the following ways with regards to documentation:

1 - This means there are no formal specifications.
2 - Documentation deliverables aren't important.
3 - There's no need for code comments or testing plans.
4 - There's no need to record anything because scrum says development of the product is the most important thing.

At the risk of going all "Psychology 101" on you, there is a definite temptation to believe that some people are saying some of these things more as an expression of their hopes, because they don't like proscriptive processes and/or writing documentation, rather than a genuine belief that this is what is intended.  There are also a few "end of the bell curve" types who do genuinely believe that code comments and testing plans have no merit, and that recording anything is somehow tantamount to KGB-style surveillance that will be used against them maliciously if the company decides to restructure.  These people are are not particularly valued by their team mates.

However, for the majority of people, these are expressions of concern about scrum's suitability to cover certain statutory or legal requirements, and the provision of a process framework for things that need to be agreed in writing or recorded for good reason.

Scrum is designed as a series of guidelines rather than a specific, one-size-fits-all framework that covers every eventuality.  Each company is different, with different working patterns, different statutory and legal requirements, and different processes and procedures.  Scrum is deliberately flexible to allow it to be implemented in different ways to suit the myriad circumstances that can be found in the real world. However, there are agile principles for a reason, and they are there to guide the practical implementation rather than to proscribe a set way of working that everyone must adhere to***.

So let's correct these misunderstandings:

1 - This means there are no formal specifications.

    Wrong.  There don't HAVE to be formal specifications if you don't want them, but there is nothing in scrum that stops you having them.  Many companies continue to feed formal specifications into a scrum process very successfully.  The difference in scrum is that these specifications are broken down until they reach a granularity whereby each task that is required to complete the specification can be completed in 1 day or less.  These tasks then form (part or all of) the backlog, and are prioritised by the Product Owner. 

Sidebar: Specifications are often replaced with User Stories in scrum.  These user stories can either be created in concert with the customer or internally as part of the process that feeds work into the backlog.  User stories are broken down into smaller and smaller chunks until they reach the size of work items, which will consist of a day's task for each area of competence.  For example, a work item will contain a development task, a testing task and a documentation task, each of which will take a day or less to complete.  The Acceptance Criteria and Conditions of Satisfaction that are part of each work item are agreed during grooming and apply to all the tasks within the work item.


2 - Documentation deliverables aren't important.

    Wrong.  Documentation deliverables form part of the product, as do any other deliverables.  By their very nature as deliverables, they are required and (normally) part of the contract for what will be provided from the supplier to the customer. Having said that, if the customer has a direct role in the specification of the software, for example where a piece of bespoke work is being delivered, documentation can potentially be delivered at release time, rather than sprint by sprint.  This is because the customer will be a stakeholder, and as such the increment that is being delivered should be demonstrated to them (and any other stakeholders) in the review ceremony at the end of each sprint.  Due to the short nature of sprints and the granularity of the tasks the customer should already know what they are getting in the sprint, and so the documentation deliverable will be less time-critical.  However,  it is only the urgency that decreases in this situation, not the importance.


3 - There's no need for code comments or testing plans.

    Wrong.  Code comments are an essential part of any sensible development process.  Staff come and go, either to other companies or other projects, but the code line remains for as long as the product does.  If there is code, someone will have to maintain it.  Even if the developer who wrote the code is the one who maintains it, if they haven't looked at that section of code for any great length of time then without code comments they will still have to work out what the code does, why it does it, what work item or bug number it relates to, and any other relevant information that they need.  These comments can also be directly linked to unit testing, in that they provide the information that allows a unit test to be written or amended.  Testing plans allow the same traceability for what, why, when and how, with the same potential link to automated testing runs, and, depending on your regulatory framework, can be an important part of your company's ISO/BS/CMMI compliance.  There is nothing in scrum that says code comments and testing plans aren't important or needed.


4 - There's no need to record anything because scrum says development of the product is the most important thing.

    Wrong.  Firstly, scrum methodology does not override regulatory, statutory or contractual obligations around auditing and record keeping.  Secondly, as a corollary to the comments above about code comments and testing plans, keeping a record of decisions made and work done is a sensible part of running a good business.  The backlog should be the record of what's happening, when, why and who has done it.  This means that whilst scrum ceremonies do not need to have audit-able minutes, there is no requirement to stop producing a record of what decisions where made, when they were made, why they were made, and who made them, nor is there any push to stop entering time sheet information (which is often vital for the company to work out its final billing to a customer) or other standard records that might be kept.  It IS true that scrum tries to remove the all-encompassing documentation of every little thing that is said and done for the purposes of back covering, but that is as much about having a decent working environment for your staff as it is about removing an onerous and often pointless exercise in blame avoidance. 


In conclusion, what this principle is saying is that large, formal, immutable documents that form the basis of the work and act as a record of what was agreed and what was eventually done do not have the same level of importance to the scrum team or customer as a working increment of software delivered at the end of each sprint that has been created in line with the agreed priorities.

And that's something that we should all be able to agree on.





*** - Obviously the ceremonies, roles and artifacts are proscribed, but they provide a framework within which any implementation that uses them can be described as scrum or a variant thereof.  There are as many ways of operating in this framework, especially in the small details, as there are companies that implement it.