Agile technical writing is a popular topic in the blogosphere (see Edwin Dawson’s recent three-part blog series). The user communication team at Klocwork is becoming more agile in fits and starts. In the last release, we joined our development team in using Xplanner, and found that it both reduced that horrible did-we-miss-something feeling and increased the visibility of our status.
In this release, we’ve resisted the urge to create a matching help story for every dev story. Instead, we create stories that allow us to focus on the highest-priority types of information: what’s new in this release, how the system works, how to get started, and how to use the tools day-to-day.
Our biggest struggle with Agile right now is how to stay on top of feature development while working on our own help-specific stories (like the current crazy-making idea of moving our help to a Wiki). Here are a few things we’ve learned along the agile way:
- “Just barely good enough” can mean documenting a feature only in the “What’s New” guide in an early iteration. This forces us to understand the “why” of a feature. It’s easier to ignore the “why” when you’re writing step-by-step procedures. Later, we’ll add information on getting started, a detailed how-to, and any necessary reference information.
- Workflow is king. If we don’t know how users will incorporate a tool into their environment and use it day-to-day, there’s no point writing a lot of words about which button to click when. So we push for details on workflow. And once a few customers provide feedback on a proposed workflow, the how-to starts to write itself.
We’re hoping these ideas will help us forge enough of a path through the agile doc frenzy to retain our sanity through the release.