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. An industry of consultants caters to making developers and product managers successful with Agile, but there is limited—if any—information on how writers can cope in such an environment. How do we know? Because in 2006, salesforce.com switched to Agile. 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.
What is Agile Software Development?
“In the late 1990’s several methodologies began to get increasing public attention. Each
had a different combination of old ideas, new ideas, and transmuted old ideas. But they all
emphasized close collaboration between the programmer team and business experts; face-to-face
communication (as more efficient than written documentation); frequent delivery of new
deployable business value; tight, self-organizing teams; and ways to craft the code and
the team such that the inevitable requirements churn was not a
crisis.” From The Agile Alliance.
The Problems We Faced When Switching to Agile
The table below lists and describes the problems we encountered as we transitioned to Agile.
Some team members other than writers experienced similar issues.
| Problem | Description |
|---|---|
| Terminology | Agile introduced new terms that confused writers and product teams. Words such as, scrum, scrum master, story point, velocity, product backlog, and especially Agile, meant different things to different people. Teams used these terms incorrectly or inconsistently; they thought they knew the correct definitions. |
| Product specifications |
Some product managers assumed Agile meant they no longer needed to write specifications for their products. Writers accustomed to reviewing specs to plan, organize, and estimate documentation requirements were surprised to discover there were no specs or information that described how products being developed should work. |
| Estimates | Writers needed to provide hourly, daily, or weekly estimates for their documentation tasks; however, they found it difficult to provide estimates if a product lacked a specification, prototype, or stated business requirement. |
| Time tracking tools | Tools used to track the accuracy of estimates generated additional work. Writers spent time learning how to use and update various time tracking applications, and writers assigned to multiple teams managed estimates in multiple tools because each team decided which tool to use. |
| Meetings | Writers felt that they spent more time in meetings than they spent documenting products. Agile includes a variety of meetings, such as sprint planning, sprint review, sprint retrospective, and daily “stand up” or scrum meetings, which require writers’ attendance. (See Multiple teams for why this hits documentation harder than development.) |
| Multiple teams | Unlike other team members, writers worked for multiple product teams and were considered a “shared service.” |
| Team loyalties | Writers assigned to multiple teams found it difficult to prioritize tasks. Each team worked towards accomplishing daily, weekly, or monthly goals, so writers had to choose which team’s priorities to prioritize. |
| Context switching | Switching between tasks, teams, priorities, or business requirements delayed writers from delivering documentation. |
| Time | Agile’s combination of new terminology, meetings, time-tracking tools, context switching, and limited product specifications caused writers to spend more time on Agile and less time writing documentation. |
| Fiction | To remain on schedule with development, writers produced documentation for nonexisting products based on evolving sketches, prototypes, business cases, or hearsay. After a product became available, writers tested their documentation for accuracy and revised files as necessary. |
Implementation Solutions
From our experience, we recommend the following strategies for implementing Agile for writers.
Note that salesforce.com abruptly switched to Agile: one day our product development team used
the traditional “waterfall” approach to build applications, the next day we used Agile. The immediate
switch helped us adapt, evolve, and solve our problems so that we could quickly develop better
products on schedule.
| Strategy | Description |
|---|---|
| Encourage patience | 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. |
| Provide training | Confusion about Agile was greatly reduced after every product team member–including writers–attended a class that explained Agile. Now, every new employee in product development is required to attend Agile training. |
| Build templates | Writing, updating, and organizing documentation plans became easier for writers after management provided templates in Google Docs. The templates list questions that help writers think about documentation requirements for products developed in Agile, and the flexibility of Google Docs lets writers change aspects of their plans as products evolve. |
| Standardize tracking tools |
Working in an Agile environment became easier for writers after all product development teams stopped using various time-tracking tools and agreed to use one, internally developed tool. |
| Pad estimates | Give your team estimates that are a little longer than what you think is necessary to complete a task. We discovered that all estimates are guess-timates, but that larger estimates were more accurate than smaller ones. Our teams tended to underestimate, so we learned to overestimate. |
| 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. Now, whenever developer head count increases, writer head count increases too. |
| Learn to adapt | It’s easier to adapt to an Agile environment when writers review its benefits instead of its challenges. Like it or not, we had to change how we worked because Agile became the permanent product development methodology. 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 are extended slightly beyond the product development deadline. Providing writers with at least an extra week allows for higher-quality documentation. 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.
| Best Practice | Description |
|---|---|
| Ask questions | Ask your team to clarify anything that is unclear to you at the daily scrum meetings. Functions of a scrum meeting include answering questions for team members and resolving any issues that are preventing the team from completing tasks. |
| Email your team | Email any product or process suggestions to everyone on your scrum team. One of the principles of Agile is to work together as a team instead of seeking direction from management alone. |
| Write fiction | Learn to feel comfortable writing documentation for half-baked products, nonexistent products, and products you can’t test. In Agile, you’re more likely to reach deadlines by writing fiction than by waiting to write nonfiction for a finished product. |
| Revise fiction | Learn to revise any fictional documentation you wrote for accuracy before it ships to customers. Insert revision reminders in documents and add revision reminders to your calendar. |
| Skip meetings | 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–an activity where 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 |
Learn to work in reverse if necessary. For example, a product might not require a documentation plan, but as you begin to write you notice a huge increase in the scope of the documentation. Agile emphasizes flexibility over processes; it’s okay to write a plan after you start writing. 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, it might not be necessary for writers to attend scrum meetings daily. Some of our writers found it useful to attend scrum meetings every other day. Take advantage of the fact that Agile means self-organizing: it’s okay if different teams work in slightly different ways. |
Team Best Practices
We recommend that writers in an Agile environment use the following best practices when working
with their scrum teams.
| Best Practice | Description |
|---|---|
| Volunteer | Volunteer to complete tasks for your team that don’t involve writing. For example, agree to test a product or to present a demo at a sprint review. Let your team know that you can do more than write documentation; build a rapport with your team. |
| Be wrong | Don’t worry about asking the wrong questions or giving the wrong answers. Agile creates a fast-paced environment where things change quickly and not everyone has the same information at the same time. |
| Speak up | Ask questions, suggest solutions, and provide feedback on products and their design. One of the principles of Agile is open communication across teams, and every team member—including the writer—can add value by expressing a unique view point. |
| Barter | Negotiate with your team if they want you to spend more time than you have to document their product. For example, tell them you can finish the documentation if someone else volunteers to write a first-draft of reference topics or provides you with code samples by a specific date. In Agile, team members are supposed to work together to help every person complete their tasks. |
| Self organize | Organize team meetings and determine how you can create or update processes that benefit everyone on your team. For example, if a product is evolving too quickly for some team members to understand how it’s supposed to work, organize weekly discussions to help clarify product behavior. In Agile, teams are self organizing, and writers can create, update, or advocate for processes that benefit everyone. |
| Be a shared service | Provide your team with visibility into any tasks you have outside of scrum so that they can work with your limited time accordingly. For example, create a user story or task for interviewing candidates or speaking at conferences. Show your team that you are a shared service and that your time is divided between multiple assignments. |
| Claim the last line of defense |
Let your team know that you’re like an additional quality engineer–you’re in a unique position to see the product holistically because you have to test the product to ensure your documentation is accurate. Communicate your value to the team as the last line of defense between shipping a product that works correctly or incorrectly. |
The Benefits of Writing in Agile
The writers at salesforce.com experienced the following after transitioning to an
Agile environment.
| Benefits | Description |
|---|---|
| Writers have more impact |
Writers have more impact because they’re considered an equal member of a scrum team that’s working together to complete a product. Plus, writers have opportunities to voice opinions, suggestions, and concerns at teams’ planning, retrospective, and daily “stand up” meetings. In Agile, writers aren’t just sitting at a desk writing documentation. |
| Writers are more visible |
Writers participate in most of the same meetings as their teammates and their daily, weekly, and monthly tasks are discussed and posted for everyone to see. In Agile, it’s no longer a mystery to developers or product managers what a writer must do to create quality documentation. |
| Learn what to expect | Writers work with a team of various personalities, processes, and time frames in which to complete tasks. Writers quickly learn what to expect from a team and how to deliver documentation accordingly. For example, some of our writers learned that it’s more efficient to document a product based on its prototype while other writers learned that they can’t rely on their teams’ prototypes for accuracy. |
| Retrospectives solve problems |
Writers notice positive results from retrospective meetings. For example, a number of writers mentioned that they needed some type of product specification to estimate documentation requirements. Product managers provided writers with specifications in subsequent sprints. |
| Self determining | Writers like the idea of determining what it is they need to do to complete tasks instead of relying on management to point them in the right direction. In Agile, the principle of self-determination increases productivity. |
| Personable environment |
Writers mingle with their teams everyday at “stand up” meetings; they get to know who they’re working with, which makes for a more personable work environment. |
| Team spirit | Writers share in the collective successes and failures of their teams; they belong to a product team as well as a documentation team. |
| Sense of ownership | Writers sense that they have ownership and influence over a product because their feedback is considered as valuable as their teammates’. |
| Features are less complex |
Writers notice that Agile removes unnecessary complexities from products. In Agile, products become easier to test, understand, and document. |
| Clearer communication |
Writers claim that Agile provides clearer communication because team members meet daily and are encouraged to ask questions and voice concerns before their productivity is blocked. |
| Know who does what |
Writers learn in planning meetings which developers and quality engineers are responsible for completing specific tasks; this helps writers know who is doing what. |
| Fixed deadlines | Writers like that deadlines don’t change in Agile: products change to meet deadlines. Therefore, writers can plan their lives outside of work (and finally take that vacation!) without wondering if a work schedule will interfere. |
| Fewer surprises | Writers agree that all of the benefits listed above work together to eliminate surprises during the product development cycle. If a team is truly practicing Agile, it’s rare for a writer to discover that he or she needs to write a brand new implementation guide or create a new online help system right before a product ships to customers. |
Summary
Writing in an Agile environment poses new difficulties for writers, but so did the typewriter and
computer when they were first introduced. The computer is a tool used for efficiency; Agile is an
organizational methodology used for efficiency. Before you can see the benefits of a new tool or
methodology, you must learn how to use it. 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.
More Information
For more information, including trouble-shooting tips and a more comprehensive definition of Agile,
read the entire Writer’s Guide to Surviving Agile Software Development whitepaper (link opens PDF).