The Agile Technical Writer

The Agile SCRUM method suggests using “sprints,” which are short development cycles of two to four weeks. Each sprint has a defined set of deliverables based on user stories (requirements).  The number of weeks in each sprint depends on the team’s preferences, and teams find a comfortable time span that works for them early in the process. My experience is mostly with three-week sprints, which, like Goldilocks said, was Just Right, neither too long nor too short for the team I was on.

Sprints  have an upside and a downside, depending on how you look at it.  For the developers, it’s all good. If they finish up all their coding before the end of the sprint, they have time for testing a little and maybe fixing a few bugs. For those of us in documentation and QA, it can be a bit more challenging depending on when the work is actually considered complete–during the current sprint, the next sprint, or an overlap between the two.

On the upside:

• Documentation in each sprint is based on of a defined set of features developed in that sprint. Deliverables are defined by the user stories, so scoping topics up front is simple.
• User stories provide a synopsis of the feature that the user wants, in simple language. Usually provided by a project owner, this information is simple and easy to understand, unlike some “old-fashioned” requirements documents!
• Sprints have a definite start and end date. The target is easy to see.
• Creating documentation agilely means you can start  topics based on what you have during the sprint, and add more detail later when more information is available. Usually this means that you create tasks first and add conceptual information, indexes, and cross links later.

On the downside:

• Features may not be as clear as you would like during the sprint planning stages. User stories might not contain enough detail to start writing before the feature is complete.
• Because the back end development has to be done first (usually) and the GUI last, major features can show up in the last days of the sprint and in the last days of development. Documenting these features can require intense effort to bring the documentation up to date with the features.
• Completing all documentation and QA tests at the end of each sprint can be very difficult to do. Usually a “hardening” sprint is included at the end of development before a release to allow some extra time for testing and documentation completion.

There are strategies to manage the downsides.

• If a feature is unclear, ask questions of the developers and product owner to get more detail. Ask “how is this supposed to work?” And “how does this help the user?”
• Participate in any road mapping sessions that your team has to get a good overall view of where the development is going feature-wise.  And take good notes! This will help your overall understanding of what may be developed over time, which allows you to plan for overall documentation development.
• Complete as much of the documentation structure as possible during each sprint, even if the features are not completely clear. Create placeholders for topics based on user stories, draft a basic description, and update that information at the end of the sprint.
• Ask for reviews as each topic is completed: don’t wait until the end of the sprint when everyone is working flat-out.
• Keep track of the user stories as the sprint progresses. Stories can, and do, change over the course of a sprint.
• Make sure the team, product owners, and Scrum Master for your team understands how much work you have to do, and what your capacity is. The product developers do this in each sprint and you must do the same to avoid being overwhelmed with more work that you can complete.
• Use the “good enough” principle for documentation. When it is “good enough” that a user can complete a task or understand a concept, move on to the next story.  If there is time for polishing, that occurs in the hardening sprint.
• If you don’t have an editor, trade-off with a peer for a copy-edit to find mechanical errors, typos, and so on. The best time to do this is two or three sprints from the release date.

Working in an Agile way is a balancing act sometimes, but for the most part, it’s my favorite way to work.  I use DITA (the Darwin Information Mapping Architecture) to structure the topics, which fits easily into an Agile shop because it allows me to chunk the documentation development by features. It’s very satisfying to have documentation and application features that match seamlessly during the development cycle, sprint by sprint.