Wednesday, 25 February 2015

Documentation Can't Complete Until Testing Completes

To some writers, the fact that we can't complete the documentation task for a development work item until the testing task has been completed  seems so obvious that it's unworthy of explanation.  However, for those people who aren't immersed in writing documentation it isn't always so apparent.  Here's an explanation for those people.

Scrum is a methodology for cross-functional teams to produce increments of a deliverable that gradually build up into the finished product over a number of sprints.  As part of this methodology, the cross-functional team members work on the sprint backlog tasks in priority order until they are all done, and then move on to the next sprint (I've used the analogy of carnivorous beetles swarming over a carcass elsewhere as a nicely graphic image to emphasise this).  However, due to the lack of multi-functional teams (a.k.a. the unicorn at the heart of scrum) most teams end up working in some form of Water-Scrum-Fall, that is, a relatively linear progression from development to testing to documentation, done in sprints with appropriate ceremonies and artifacts***. 

In this linear situation, the developer will complete the development task, the tester will test the work, and if they find a problem they will refer it back to the developer, who will fix the problem and send it back to testing, and this process will continue iteratively until the work passes and the testing task is complete. (Some referrals might be put into the release backlog if they do not affect the acceptance criteria of the work item, but that doesn't affect the documentation in this situation). 

The reason that the documentation task cannot be completed before the testing task is completed is that it is ONLY when the testing task has been completed that no more changes will be made to that piece of work.

At this point the standard argument against you is: "Well, the developer will have followed the acceptance requirements, and wire frame, and conditions of satisfaction and [any other artifacts provided] and so the writer can complete the documentation once the developer has completed their task." 

This is true in theory, just not in practise.  Let me explain by way of an example.  The designer mandates that 4 fields need to be added in a row because users will always fill in field A, then field B, then field C, then field D.  A wire frame is produced that shows the fields as:

FIELD A        FIELD B        FIELD C        FIELD D 

At task implementation time, the developer realises that at a lower resolution these fields will not all be visible without scrolling, and, as scrolling is frowned upon, they actually put the fields as:


The tab flow goes ABCD, the natural flow is correct (for the European market where this software is sold) and it ensures that the developer has met both the user requirements and the development rules.  However, if the writer takes a screen shot at this point in time, checks that the fields do what they are expected to do as per the artifacts and sets their Documentation task to done, what happens if the tester realises that your company stopped supporting that low resolution last year, so actually it's ok for the developer to revert back to a row in line with the designer's original plan?  The developer makes the changes, the tester passes the testing task....and the documentation is wrong, but the writer doesn't know it. 

The more developers and/or scrum teams you have, the more likely it is that changes that materially affect the documentation will be made to a piece of work after the Development task has been completed for the first time. To be clear, it is NOT ok to assume or even mandate that either the developer or tester tells the writer about this, in the hope that that will solve the problem and make your team more "swarm of beetles" and less "line of ants".  Developers and testers don't know what will materially affect the documentation, so they'll have to tell the writer about lots of things that don't matter to the writer, which wastes time for all parties, and, more importantly, this puts the onus onto people to to catch and solve problems which should be prevented from ever happening by the system itself.  And that system should include writers not being able to complete their tasks before testing have completed theirs.

*** - Now, if you DO work in a multi-functional team, you can develop a piece of work and then complete the documentation task before testing having finished. But be honest, you don't work in a
multi-functional team.  Don't feel bad, neither does anyone else.