Here's the rub for technical writers: Converting to Agile methods forces changes to how we create and manage documentation. In our case, documentation is supposed to be handled "like code" within the Scrum/sprint process, subject to the same requirements. So, here are the implications we deal with:
- No lagging a sprint behind, as some shops do; we must be "shippable" at Review.
- We write up new documentation and revise the existing at the same time as it's being coded and tested.
- Within the sprint, there's a bit of a waterfall, just as exists for testers: we can't see what's not coded yet. Ends of sprints are quite brisk for writers.
- We focus on continuous, automated builds, in support of being ready-to-ship.
- Our build engineers worked hard to create a continuous, automated build environment to support Agile, meaning that checking in code triggers an immediate rebuild. The rebuild success or failure is broadcast throughout Production, reporting errors and test failure details, for immediate response.
- Continuous integration builds allow testers and writers to always work with "real" builds.
- Automated builds of documentation into Help sites and manuals mimicks this system, and it allows testers to evaluate documentation based on what will actually ship.
- In reviews, we provide links to the actual, finished documentation changes.
- Docs are part of Definition of Done; incomplete doc tasks block the entire team.
- Tempting as it would be to push incomplete doc tasks to the following sprint, we don't show any stories as complete if the docs aren't there.
- To keep the tech writer (a shared resource) from blocking the team's ability to complete, other team members must be able to update doc source.
- Integration and overall review of release documentation happens during final regression sprints.
- Editing for document flow and consistency is largely deferred until the very end, by necessity. The more cooks in the kitchen, content-wise, the more daunting this is.
- Final regression before a general release is the only opportunity to force teams and stakeholders to review entire documents, versus the single topics affected by a given sprint.
- All production work (new batch scripts, archiving, setting up manuals with printers, updating publication sites) also happens during this period, so the documentation team is very crunched at a time when the rest of production experiences a relatively restful break from typical sprint work.
Since a goal of Agile is to have teams work productively at an even, sustainable pace, I see real challenges in this approach to documentation: to avoid a train wreck during regression, I suspect the integration and editing functions need to be performed continuously throughout the entire release. I think this argues for placing technical editing in a supporting function outside of the teams, with an Editorial Review required within Definition of Done for any doc tasks. Do any of you manage it this way?
