Although I’ve been part of an agile development team for the last few months, until recently my user documentation tasks have not been part of the sprint backlog. But this time, my tasks are on the board! (I realise that if you are not au fait with the arcane language and practices of agile, you may find this post a bit obscure.)
Agile teams are self-governing to the extent that team members decide which tasks they can complete within the allotted time, and self-monitoring in that they meet on a daily basis to report on progress, plans and obstacles – or, in agile language, “impediments”. For our current sprint, our engineering team selected four stories from the product backlog, which were all enhancements to a particular existing feature. For the first time, we included a user documentation task for each story, which I have been responsible for.
We had agreed in advance that the user doc task was defined as the user-facing explanation and instruction for the particular enhancement. The task would be “done” when it had been written, reviewed by subject matter experts, and incorporated into the source files for the manual or online help. The publication and translation of the entire manual or online help system was not included in our definition of “done”. This parallels the way in which a coding task is “done” when it is ready to be integrated into the next deliverable build, but the actual packaging and delivery of the build is outside the scope of any particular sprint.
For this first sprint, this has worked pretty well for a number of reasons:
- the other members of the team know me and I know them, so there was no “social barrier” to my participation, and there was good and positive response to all my requests for information and review
- the team are following a behaviour driven development method (BDD) and are writing feature files for Cucumber; I took part in the meetings where the feature files were drafted
- the stories were enhancements to an existing product I knew well
- the enhancements were pretty self-contained, and didn’t involve much in the way of changes to other features
- from the user’s point of view, the enhancements were pretty straightforward, so there was never a danger that the doc tasks would take longer than the coding tasks
I know that these factors won’t remain true for all sprints. There may well be product enhancements that demand a very large amount of revision to the user-facing documentation, while being pretty easy to code and test. Other constraints may come to bear on team members making it less easy for them to provide the support that the tech writer needs. In cases like these, completing the doc task may well take longer than the coding task, and may legitimately delay a story getting to “done”. However the inclusion of doc tasks on the board for this sprint has been a positive experience for me and the rest of the team, and has given me the confidence to address more complex user documentation challenges in future sprints.
Excellent post and very helpful for me. I’m just getting my feet wet in Agile sprints. My biggest challenge is getting teams to remember to include me in their planning. I often don’t find out about sprints until they’ve got half their code done.
Going through the same thing! I’m a week into a 3-week sprint with documentation tasks on the board for the first time. I’m new to the team, new to the product, and new to the company, but they seem to understand the need for good docs and are eager to help and make this work. I’ve been attending all the planning meetings and demos and scrums, so I am rapidly getting a feel for how things are supposed to work.
The doc tasks are written as individual micro stories that support specific development task/macro stories (rather than include doc time on dev cards). This will allow the dev tasks to be done whether or not I can finish the doc pieces. The biggest challenge for me is updating just the text that applies to the current task, and leave the unknown stuff, well, unknown. I tend to want to “fix” the whole chapter or sometimes even book, when the project is too young to know exactly how everything will work yet.
I think this will work because it is an update to a mature product, there is lots of existing documentation (so I can easily identify, for example, that changes need to go into Chapter 6 or into the Quick Reference or whatever). Toward the end I suspect I’ll need to go off the board to do stuff that isn’t necessarily tied to distinct development tasks, but we’ll see how that works out later.
I’ve worked both within the stories, and as separate stories in the sprint. I find that keeping the tasks within the stories results in more engaged dev team members, since the points don’t get claimed until the docs are done! (Documentation is part of our Definition of Done.)
However, if it is clear that the docs wouldn’t be able to complete in the sprint, I have moved them off to their own stories, broken out so that I can complete the story in the sprint. I have to admit that this is more because I hate to hold up stories than because it was the “right” thing to do.
The other thing I do now is include writing tasks unrelated to any particular story, but related to the product as my own Technical Communication story. For example, if I need to do some indexing or write some overview material, I create a story. This ensures that the right amount of QC time is allocated, and helps the team understand what you do with your time