The Agile development methodology for software development involves creating and testing pieces of a product in small periods (called iterations or sprints). It is contrasted with the waterfall process, which is more of one requirements-gathering effort followed by development and then testing, and finally a single release. This methodology is gaining popularity, and it presents certain challenges for technical communicators. Having worked in my organization’s flavor of Agile for a few years, I’d like to offer a few suggestions for Agile survival.

Challenges for the Agile Writer

For the suggestions to make sense, first I’ll explain some challenges. In a waterfall process, when all requirements are written up front and are specific, the writer has something fixed to go from. We can use the requirements document to do some writing ahead of time so that it’s not all left until the end when deadlines are imminent. In Agile, requirements are not completed at the beginning, but as the project progresses, and are written in the form of use cases or user stories. This form of requirement describes a function that the user is supposed to be able to perform using the software. The developers then build that capability into the product. (In our flavor, we have interaction designers and sometimes business analysts to help gather specific requirements for user stories and tasks and then design how the features should be built.)

Agile releases take place regularly, so the writer has a short amount of time to produce documentation. Granted, the amount of functionality per release is smaller, but Agile lends itself to fast-paced development, which means fast-paced documentation. There is only so much time to document the new features.

Another principle of Agile is a close partnership with the customer. The development team checks in with the customer regularly to make sure the project is on the right track and delivering what is needed. This means that changes may occur. There may also be rescheduling as user stories are prioritized and reprioritized. (A challenge here for the project leadership is to avoid scope creep.) Any time the schedule changes or requirements for individual user stories change, the writer is affected because he needs to know what should be documented for the next release.

Suggestion 1: Find a Way to Monitor the Schedule

Whether the project leadership use a spreadsheet, software, or a SharePoint site to manage the user story schedule, find out how they do it and get access to it. You’ll save yourself a lot of the frustration that comes from finding out something has changed when you have only a couple of days left to revise what you’ve already written. Keep constant tabs on the schedule so you know what is going to be released and can prioritize your work accordingly.

Also attend iteration meetings and/or scrum meetings whenever possible so that you hear what challenges the developers are having and any announcements that may be made about the schedule. Because a scrum meeting is a daily opportunity to get together, it’s a place that project leadership may make announcements you should know about. Sometimes the only reason I learned about an ongoing discussion or a functionality change is that I went to scrum.

Suggestion 2: Use Conditional Tags in Authoring Software

If you use authoring software that allows conditional tagging, use it to exclude unfinished work from your output. This allows you to create content for what you expect to be released, and then if something changes, apply a tag called something like “Unfinished” to that content and exclude it so it doesn’t go out with the rest. Then, later, when the features are going to be released, you have content already in place, and you can finish it up and publish it.

Suggestion 3: Find and Use the Maximum Time Available

Depending on the schedule and frequency of your iterations or sprints, find out when your absolute deadline is. It may be that the deadline that applies to the developers may not need to apply to you. For example, a couple of projects I work on have a schedule two-month cycles, after which we release. Each cycle consists of three two-week iterations and a hardening period. The developers may say that the code complete date for each cycle is the last day of the third iteration, but in the hardening period, they fix bugs that were introduced during the iterations. The testers are also making sure that new functionality hasn’t broken existing functionality. This means that I have something of a grace period of a week and a half to work on documentation for the release while the features aren’t changing.

This separate deadline may especially be applicable if you are able to serve up your documentation somewhere other than in the software itself. However, it can be beneficial to have the testers verify the accuracy of your content, so take into account the fact that they have a testing schedule to adhere to.

Because development of functionality sets can cross iterations, I’m worried about meeting deadlines from cycle to cycle rather than iteration to iteration. The project managers accept that. This gives me a nearly the entire two months to plan what I need to do, develop the content, and run it through a review process, with that hardening period at the end to work on any last-minute adjustments.

Suggestion 4: Communicate with the Customer and Users

Since Agile encourages communication with the customer, there shouldn’t be any problem with your doing it. Take advange of this opportunity to find out what the customer wants in the way of help and what the users want by talking to them directly if possible.

Talking with the customer and users will also help you prioritize your work. You can find out what kind of help or instruction they need the most and plan accordingly.

Suggestion 5: Leverage User Stories to Write Task-Based Topics

Standards in the field point to writing in small chunks of information that are task-oriented because users want to complete tasks. They don’t typically want descriptions of what little pieces of functionality do.

Because user stories are generally written as tasks or functions that users may perform, they can lend themselves directly to your task-based writing. For example, a user story that reads “Allow the user to customize the search parameters,” you could create a corresponding task topic entitled “Customizing Your Search” or “How to Run an Advanced Search.” Understanding how the user stories translate to task-based topics can help you estimate the time needed to document the features.

Writing in short chunks also allows you to select various chunks of information for use in different flavors of your documentation.

Conclusion

Working in an Agile environment has its challenges, including the difficulty in planning work. I’m the kind of person who doesn’t like surprises, at least in the workplace. Doing the things I’ve suggested have helped me be more agile myself—to respond more quickly to changes and the fast pace.

I’ve been thinking about this topic because recently I moderated a panel discussion in the Intermountain STC Chapter. The topic was Agile documentation and how to get along. As moderator, I tried to keep my nose out of things other than to ask questions, so I thought I’d post my perspective. Thanks to the panelists for a great discussion.

Related entries (auto-generated):

Five Skills for Managing Documentation Projects in an Agile Environment

Release Scrums: An Important Resource for the Agile Technical Writer

A Bug-Fix Cycle at Project End Is Good for Everyone

Teaching Project Management How to Work with Technical Writers

The Technical Communicator as Project Manager