Factors that Determine if Documentation Should be in the Definition of Done

When we talked about whether documentation should be in the Definition of Done, there were 6 factors that spoke directly to the answer for teams that weren't multi-functional (which is the vast majority of teams that practise scrum). That article focused on what combination of those factors would allow you to add documentation to the Definition of Done (DoD); this article looks at those factors in a bit more depth and explains why they are so important.

Let's remind ourselves of the factors which need to be looked at:

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?

Don't forget that for single- or semi-functional teams the question of whether documentation is part of the sprint deliverables is not a factor; this is about whether you can deliver documentation at the end of each sprint, and if you can't then you (or rather your company) shouldn't commit to providing documentation as a sprint deliverable.



1 - Can anyone other than the designated writer(s) complete the documentation tasks?

The answer to this question determines - for the specific purpose of working out if documentation should be in the DoD - whether the team is single-functional or semi-functional.  If there are, for example, 6 developers, 2 testers and 1 writer, and only the writer can produce documentation, the team is single-functional.  If one or more developers or testers can produce documentation to the same standard as the designated writer then the team is semi-functional. Note that adding another specialist writer to the team won't make the team semi-functional, because documentation can't complete until testing completes, so although this will provide more manpower to get the documentation done, it won't change the inherent problem that non-multi-functional teams face - the need to work in a linear process within each sprint.  If one or more developers or testers can produce documentation, they are able to take on the documentation tasks as well as tasks in their own speciality earlier in the sprint.  This is what makes the team internally agile. The more developers and testers that can produce documentation to the correct standard, the closer the team is to being multi-functional (for the purposes of providing documentation).


2 - What proportion of documentation can be done quickly by the writer, e.g documenting a bug (as opposed to complicated enhancements, for example)?

This is the key metric that determines how much work the writer can do before testing have completed their tests, and how much will have to be done after testing have completed.  The development team should provide information for each bug in the form of "This is what was happening", "This is why it was a problem", "This is what happens now". Once the developer has done this work and sent it for testing, it is rare for this information to change (i.e. testing might find an issue with the developer’s fix, but the "This is what happens now" information rarely changes), so the writer can document a bug before it's been tested and move on with a low chance of rework later on. However, if a writer is working on enhancements, especially UI changes, then there is a much higher chance that any issues found in testing will affect the documentation, therefore the chance of rework is much higher, therefore the chance of the writer completing their tasks before the end of the sprint is much lower.  For a single-functional team this proportion needs to be very high to allow documentation to be part of the DoD, otherwise documentation will be a likely point of failure when determining if a sprint completed successfully.

One thing to bear in mind:  Because of the inherent fluidity of new work and the fact that a large piece of development might be done over more than one sprint, and it is easier to document it as a whole once it’s completed (so you can fully understand it, take screen shots, work on it as one piece of work rather than task-switching all the time, etc), this factor is something to think long and hard about.  If you have a lot of enhancements to document, especially ones that tie together to make a few large enhancements, you really should opt for documenting outside of the sprint cycle, no matter what your answers are to the other factors. 

If documentation IS part of your DoD, you’ll be at the end of the accordion, and if development or testing don’t hit their deadlines within the sprint then the writer will get squeezed and squeezed until either quality or completion  - or both - become an elusive dream. And if development and testing DO hit their deadlines then they’re twiddling their thumbs for several days while you write the documentation. It’s an intractable problem that is best solved by removing documentation from the DoD and working in sprint bundles to make development and testing more efficient, and to minimize rework for the writer, but if documentation is part of the sprint deliverable then it's something that has to be managed as much as possible.



3 - Is the quality of the input to the documentation tasks reliably high and consistent?

By "high" we mean "All the information that the writer needs to document as much of the work as is possible before development and testing have completed, for example, wire frames showing the expected field positions, a complete explanation of the functionality and what it will be used for, a complete listing of all parameters that affect the new work or are affected by it, and any other information that the writer needs to provide to the customers."

By "consistent" we mean "Every work item that is in the sprint has this information in it, every time, without fail."

If the quality of the input is not both of these things then the writer will have to spend a lot more time finding the information out, which can only be done after testing have completed, and again, the writer is much more likely to fail to complete their tasks by the end of the sprint.  It's also much more inefficient in general terms; the information is all there, but the writer will have to get it manually from developers, designers, the Product Owner, etc, so this is good practise anyway.


4 - Is the number of deliverable less than 2 (or if 2 or more, can they be single-sourced)?

Deliverables might mean traditional documents such as help files and release notes, but equally it could be editing help messages and other on-screen text, writing API documentation, and so on.  The point of concern here is two-fold: Firstly, will the writer have to enter the same information in more than one deliverable in any given work item (unless it can be single-sourced, in which case the practical answer is "No") and secondly, Will the writer have to complete (format and prepare for release) more than 1 deliverable at the end of the sprint?  If the answer to either of these is Yes, then the writer has to either add the same information into multiple deliverables, or different information into different deliverables.  Either way, there is an overhead in these scenarios that adds more required time onto the documentation.


5 - Are there proscriptive standards and templates for the documentation that is being produced?

What is one of the most difficult and time-consuming things for most people to do?  Making a decision.  What is a guaranteed way to ensure inconsistent and therefore poor quality documentation? Letting people make individual decisions about formatting, language, and so on.  Having incomplete - or missing - proscriptive standards and templates therefore both costs more time AND lowers quality.  Even if a writer is good at making consistent decisions, there is still the possibility - the probability, in fact - of errors or inconsistencies being made from time to time, and as the decisions will have to be made every time they work on a documentation task there is an in-built bottleneck and inefficiency there. Anything which prevents the writer from writing should be seen as an impediment by the Scrum Master and as waste (in LEAN terminology) by the company.  So perhaps a more apt question would be: Why WOULDN'T you have proscriptive standards and templates?


6 - Are complicated enhancements front-loaded by the team to allow the writer to work on them as soon as possible?

Because documentation can't complete until testing completes and because, as noted in #2 above, there is a much higher chance of rework with an enhancement, any enhancements that require significant documentation should be front-loaded by the developers if possible.  This is not always possible, because development need to start getting work to testing, and complicated enhancements often take longer to do than bugs, so bugs get done first to ensure that testing have work to do as soon as possible in the sprint.  Bugs can also be "quick wins" for development.  There is an inherent tension here, because bugs can be normally be documented quickly (especially if the quality of the input is high and consistent and you have proscriptive standards) and also can be estimated more easily.  If you have 10 bugs left, for example, you will know that all things being equal it will take you 2.5 hours to document them (or whatever your rule to thumb tells you - mine says 15 minutes per bug as an average).  But if you have 10 enhancements, all with a different number of story points then you can still estimate them, but it's something you have to work out as opposed to being something you know.  I know that 15 minutes is enough time on average to document a single bug because over many years of experience 15 minutes has proven to be a reliable estimate for me in many different situations.  But I can only estimate how long it will take me to document an enhancement.  That estimation may be more accurate as I learn the product and participate in the grooming to properly understand the work that will be done, but I will never have the level of confidence in it that I do with my bug estimates.  The larger and/or more complex the enhancement, the less accurate your estimate will be.  And as development for a single-functional team is linear (i.e. each sprint follows a Waterfall pattern) and documentation comes at the end, it's much easier to tell if you will complete on time if you only have bugs left to document.  The more enhancements that are left until the end of the sprint to document, the greater the chance of you failing to complete your documentation tasks and being the point of failure.  This is doubly annoying because it looks like the writer has failed, but actually it's the system that has allowed the whole team to fail by not understanding what each function within the team needs, and when they need it.



Once you've understood these factors you can use them to help make your decision on whether documentation should be in the DoD.  Good luck!