“Originally, the methodology did not include documentation, but many organizations have figured out how to use it...” From Alyssa Fox & Meredith Kramer—Mobile and Agile:The Floating Writer's Survival Kit
Many writers are trying to figure out how to meet deadlines, write quality documentation, and stay sane as their software companies switch from the traditional “waterfall” method of development to the increasingly popular Agile methodology. Our Documentation and User Assistance team found few resources to help us work with Agile, even though our executives, managers, and Agile coaches were determined to help us succeed. From our experience, we created strategies and best practices that help us thrive (and enjoy) writing in an Agile environment.
Are You Really Agile?
If your company implements Agile methodologies in a haphazard manner, you may not really be Agile. And if you aren't really Agile, you may not find a lot of benefit. The rest of this document may help you in small ways, but it can be tough to cope with sort-of-Agile or mostly-Agile implementations.
The following are minimum criteria for being able to get full value out of an Agile environment:
• Executive support. It may scare executives to imagine a company full of self-organizing groups in charge of the product development process, but Agile doesn't work unless those executives take the risk and respect rules around scrum team organization.
• Whole teams. Development, documentation, QA, and product management should be represented at all Agile meetings.
• Training and coaching. Organizations may latch on to a few elements of Agile methods, like just-in-time development or light organizational structure, but it really takes all the parts to make it work well. Your organization should invest in training and coaches to really make it work.
The good news is: you may still be able to use any of the following techniques to improve the documentation process in a not-entirely-Agile environment.
We recommend the following strategies for implementing Agile for writers.
Our executives understood that all development team members, including writers, would experience an adjustment period transitioning to Agile. No one expected a perfect transition. Managers communicated the need for patience across the organization.
Every product team member—including writers—should attend a class that explains Agile. Every new employee in product development should be required to attend Agile training.
Writing, updating, and organizing documentation plans became easier for writers after management provided templates. The templates help writers think about documentation requirements for products developed in Agile, and allows writers to change aspects of their plans as products evolve.
Standardize tracking tools
Working in an Agile environment is easier if all product development teams use the same tracking tool. Ours was internally developed, but there are many commercially available.
Give your team estimates that are a longer than what you think is necessary to complete a task.
Provide clear definitions
Concepts such as “getting to done” became clear to writers after management provided definitions with examples on an internal wiki page and on slide decks used at sprint reviews.
Hire more writers
Switching to Agile immediately exposed the need to hire more writers to ensure quality documentation. When developer head count increases, writer head count should increase too.
Learn to adapt
It's easier to adapt to an Agile environment when writers focus on its benefits instead of its challenges. We've learned to expect more changes, and to spend more time out of our cube talking to team members.
Extend documentation deadlines
Writing in an Agile environment is less stressful when documentation deadlines extend slightly beyond the product development deadline. Providing writers with at least an extra week allows for higher quality. However, this also opens the door to accumulating more debt. Anything more than a week seemed to increase debt.
Daily Best Practices
We recommend that writers in an Agile environment use the following best practices daily.
Ask your team to clarify anything that is unclear to you at the daily scrum meetings. That’s what the meeting is for.
Email your team
Email any product or process suggestions to everyone on your scrum team. Agile means working together as a team instead of seeking direction from management alone.
Learn to feel comfortable writing documentation for products you can't test yet. You’re more likely to meet deadlines by writing fiction than by waiting to write nonfiction for a finished product.
Learn to revise any fiction before it ships to customers. Insert revision reminders in documents and add revision reminders to your calendar.
Skip meetings that don't add value to the documentation. For example, it might not be necessary for writers to attend code review meetings between developers and quality engineers.
Schedule office hours
Schedule a few hours on your calendar each week to answer documentation related questions for your scrum team (or for scrum teams who aren't assigned a writer). Agile is a proactive environment: let developers and product managers come to you.
Organize documentation “blitzes”
Organize weekly or monthly documentation blitzes—a time when your team works together to review and find flaws in each other's documentation. Blitzes help ensure accuracy and introduce writers to products they might not be familiar with.
Write bottom-up as well as top-down
Agile emphasizes flexibility over processes; it's okay to write a plan after you start writing topics. Do what you think is best for you, the team, and the product.
Learn what to ignore
Take what you can from Agile and ignore the rest. Agile focuses on software development, not writing. For example, attending daily scrums only twice a week may be enough. Agile means self-organizing; it’s okay if different teams work in slightly different ways.
The short answer to every question is: speak up! Agile relies on face-to-face interaction, frequent updates, and team members confident enough to volunteer input, whether good or bad.
What do I do if I'm not invited to meetings?
Find the person who runs the meeting and ask to be added, and be prepared to explain why. You may need to reassure the person that you won't slow down the meeting, and remind them that the more you learn, the less time you need from subject matter experts. Escalate if needed. If you can't attend scrum meetings, sprint reviews, and similar meetings, the organization probably has bigger problems that need addressing, and you aren't really writing in an Agile environment.
What do I do if they think Agile is a license not to write functional specifications?
If you have Agile coaches or anyone monitoring the health of Agile implementation, ask for help. If you don't, we've found that holding meetings, and suggesting in the invite that answering the following questions will save attendees from having to attend the meeting produces results. If you produce the questions, there's almost always someone on the team willing to give you answers.
Also, be willing to do more digging and playing. You'd be surprised at how little you may need to get started.
How do I cope with last-minute code check-ins?
Some organizations insist that documentation should not be held to the same cycle as development and QA, but of course this just leads to more debt being accumulated. Some organizations define “done” in such a way as to leave a little wiggle room for those Friday afternoon checkins.
The best way to cope with this is to help manage the process so that late checkins don't occur. Bring up in sprint review meetings that any UI-affecting work should be done early, not late. Or, remind folks that their work may not get translated, or will stick out as possibly of lower quality without proper time to review online text and other steps.
If someone really does check in a hunk of code at the last minute, with a lot of documentation ramifications, remind the team that the whole team isn't done until all the work is done, and ask for help. You may not get help the first time, but the wonderful thing about scrum is that team members get the chance to learn from their mistakes and improve every month.
Writing in an Agile environment poses new difficulties for writers, but so did the typewriter and computer when they were first introduced. With widespread support, patience, and best practices from our managers and executives, we learned how to use Agile and discovered that the benefits it provides writers outweighs the struggles we encountered when learning how to use it.
For more information, including suggested daily practices, team best practices, and a list of the benefits to writers from working in an Agile methodology, read the entire white paper at http://media.developerforce.com.s3.amazonaws.com/techpubs/agile_writers_guide.pdf.
About the Authors
Gavin Austin is Lead Technical Writer at Salesforce.com, the worldwide leader in on-demand customer relationship management (CRM) services.
Mysti Berry is Principal Technical Writer at Salesforce.com./em>