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.
|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
|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.
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.
|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
|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.
|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.
|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.
|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.
|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
|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 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 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.
|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
|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
|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
|Writers have more
|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
|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.
|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.
|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
|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
|Writers notice that Agile removes unnecessary complexities from products.
In Agile, products become easier to test, understand, and document.
|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
|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.
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.
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).