A Writer's Guide to Surviving Agile Software Development

7 September 2011

Gavin Austin
Salesforce.com

“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.

Implementation Solutions

We recommend the following strategies for implementing Agile for writers.

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

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.

Build templates

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.

Pad estimates

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 questions

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.

Write fiction

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.

Revise fiction

Learn to revise any fiction 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—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.

Troubleshooting

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.

Summary

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>

Article Rating

Current rating: 0 (0 ratings)

Comments

Krystian Kaczor, CSP,CSM, 9/12/2011 10:55:46 AM
It's interesting to see Scrum from a Technical Writer perspective.
Andreea TOMOIAGA, CSM, 9/13/2011 5:59:22 AM
Hi Gavin, Misty, in my opinion this is a very interesting article. I would like to ask you regarding the templates that you considered - how much restructuring would need to take place when starting from the initial templates provided by the organization in the traditional manner? Thank you & best regards, Andreea
Gavin Austin, 9/13/2011 11:05:22 AM
Hi, Andreea. If anything, Agile helped us streamline our doc plan templates, which used to be lengthy Word documents. We moved our original doc plan template into GoogleDocs and let writers organize their doc plans based around their own working styles (some writers like to organize content in spreadsheets, tables, text, etc.). In the spirit of Agile, GoogleDocs let writers plan their projects how they see fit, and our only guideline is that writers complete a simple checklist to gather their thoughts around impacts to other areas of the application (other features, user permissions, licenses...).
Aniruddha Ray, CSM, 10/2/2011 1:36:12 AM
Hi Gavin
Brilliant analysis of Agile from the Tech Writer POV. I have seen the unique problems Technical Publications team faces in adopting Agile. The point you made about involving coaches is spot on. I also think that the team should discuss the problems deeply in the retrospective meetings and try out innovative ideas (without breaking the principles).
Few ideas that the team (that I mentored)tried were -
1) The tech pubs team took up stories done by the engineering team in previous sprints.
This has its pros and cons. Stories get completed (done done) in 2 sprints OR the stories have to be split between Engineering work and Documentation work.
Though I was VERY sceptical of this mode, it worked. (we had plans for releases every 4/5 months.
2)The doc team can create the template (the TOC, headers, general content etc in the initial sprints, when the Engineering team is busy with "spike solutions" and then during later sprints, add story wise content based on sprint plan.
Cleaner approach, but very difficult to do unless the doc team is very agile-mature and dedicated to the team. (often documentation, UI and Performance teams are shared between scrum or project teams and then this approach becomes a nightmare.
Violaine Truck, CSM, 10/4/2011 5:15:24 AM
Hi Gavin! It's a relief to read your article and share your guide with my PO and team members. Is there a way to discuss this subject further on some dedicated forums or by email ? I am a sole writer in my organization and just got my training. This works a little different when you are a sole writer than when you are in a team of techwriters. Here, my team is made of developers. For example, explaining what you do to developers is a brand new concept for me, having them validate what I write sounds opposite to best practices. I wish I could share my thoughts with other confronted with Agile as Tech writers. Do you know where I should look ?
Gavin Austin, 10/4/2011 9:24:16 AM
Hi, Violaine. It sounds like you're experiencing the same issues the writers at Salesforce.com confronted when switching to Agile. We, too, found very few places to look (if any) to help us figure out how writers can easily complete their tasks during each sprint. However, it sounds like you're on the right track. Since your team is open to learning about what it is you do, you might want to create a user story to present your functional role to the team. Such a presentation would give your role some visibility and could eliminate the repetition of having to explain to each developer what it is you do. Furthermore, it could be a great Q&A forum to solve any issues you're experiencing with Agile. Also, Aniruddha RayΓÇÖs suggestion of discussing issues in retrospective meetings has worked brilliantly for us. Personally, I've found that once developers see what a positive impact writers can have on a product (QA, UI text, user experience), they're eager to work with the writer. To set up a time to chat, just click the Contact Gavin link under my Bio. Thanks!

You must Login or Signup to comment.