Wednesday, 25 February 2015

Should Documentation be in the Definition of Done?

Welcome to the thorniest, most contentious question is the world of agile documentation.

If you've discussed this with many people, you'll have probably heard views that range from "Who cares?" (thank you cynical developer-types) to "It ABSOLUTELY MUST/MUST NOT be in the Definition of Done!! Anything else is madness!!!" (thank you dogmatic autodidacts) and everything in between (thank you normal people). 

So let's get one things clear from the outset: There is no objectively-right-in-every-situation answer to this, only an answer which is right for your situation.

This is why you will hear such a broad and contradictory range of opinions on the subject.  That's not to say that some of those opinions aren't correct for your situation, but what works in one scrum team situation might not work in another, even within the same department, let alone the same division or the same company.

There's a good reason that there is no one-size-fits-all answer, and it's entirely to do with the unicorn at the heart of scrum.  Truly multi-functional teams are like unicorns - very desirable and yet seemingly a myth - and as such it isn't possible for most team members to pick up any given task.  Teams range from the entirely "single-functional", where a developer can only develop, a tester can only test and a writer can only write, through "semi-functional", where, for example, some developers and writers can also test, some testers and developers can also write and some testers and writers can also develop, up to truly multi-functional, where any member of the team can pick up any task. 

For a truly multi-functional team, the decision on whether documentation should be in the Definition of Done (DoD) is based simply on whether documentation is part of the deliverable due at the end of each sprint.  If it is, then it's just another task and documentation is in the
DoD, if it isn't part of the deliverable then it isn't in the DoD***. 

Outside of truly multi-functional teams though, there are several factors that need to be taken into account:

1 - Can anyone other than the designated writer(s) complete the documentation tasks?
2 - What proportion of documentation can be done quickly by the writer, e.g documenting a bug (as opposed to complicated enhancements, for example)?
3 - Is the quality of the input to the documentation tasks reliably high and consistent?
4 - Is the number of deliverables less than 2 (or if 2 or more, can they be single-sourced)?
5 - Are there proscriptive standards and templates for the documentation that is being produced?
6 - Are complicated enhancements front-loaded by the team to allow the writer to work on them as soon as possible?

(See here for a more in-depth discussion of why these things are required if you're not sure.)

For the purposes of this discussion:

    If #1 is a NO, then the team is a "single-functional" team.
    If #1 is a YES, then the team is a "semi-functional" team.

For a single-functional team:

    If #2 < 75% then documentation should not be in the DoD.
    If #2 = 75% - 85% then documentation should only be in the
DoD if #3 - #6 all = YES.
    If #2 >= 86%  then documentation should only be in the
DoD if at least 3 out of #3 - #6 = YES.

For a semi-functional team:

    If #2 =< 50% then documentation should not be in the
DoD.
    If #2 =< 75% then documentation should only be in the
DoD if #3 - #6 all = YES.
    If #2 >= 76%  then documentation should only be in the
DoD if at least 3 out of #3 - #6 = Yes

If you can't answer YES to at least 3 out of #3 - #6, then for a single- or semi-functional team documentation should not be in the
DoD, no matter what the answer to #2 is.  This is because those 4 questions determine whether your processes and standards will provide enough support to the writer to allow them to get the documentation done without a significant lag at the end of sprint.  If less than 3 are YES, then there are too many possible problems for the writer(s) to overcome.  (There's no absolute guarantee that a writer will face problems, but in the real-world situations to which this applies you shouldn't assume everything will be smooth sailing all the way - that's just unrealistic.)

 A note about the numbers: No sprint should be more than 80% full, to allow for contingency.  If #2 <= 85% for single-functional teams or <= 75% for semi-functional teams, then you are getting too close to using up all of your writing contingency by asking the writers to work on complicated work items that are likely to take longer, and have a higher expectation of rework if the writers works on them before testing has completed.  These figures are therefore partly a matter of logic and partly a matter of realism.  In the spirit of scrum, you should adjust them based on your own experience within a mature sprint team with a settled velocity.

You may have noticed that for both single- and semi-functional teams I have nowhere mentioned whether documentation is part of the sprint deliverable.  If you did notice, well done and gold star to you!  This is a key point: If your team does not have the skills, processes and standards in place to allow documentation to be completed in-sprint, then it should not be part of the sprint deliverable.  This is an issue that should be decided before agreeing a contract with a client. 


In summary, development is a process and some things simply have to be done in order. Agile helps with that, but, unless you have a truly multi-functional team, it doesn’t change it. Therefore, it's fair to say that to the question of whether documentation should be in the
DoD, there isn’t a right answer, just answers that have varying degrees of usefulness for your situation. Hopefully the factors listed above will help you make that decision.




*** - There are other good reasons why documentation might or might not be in the
DoD in this circumstance - every team, product and company is different, after all - but in principle this is the sole reason, and there's no need to muddy the waters by talking about the possible differences in business process or contractual obligations.