Writing in an Agile World


Sarah Johnson explains the role of writing in an agile world and how to educate your team members. Remember, agile takes into account that each situation is unique, and you need to determine what makes the most sense for your particular Scrum team.

We’re going agile, they said. It’ll be great, they said. They weren’t writers.

For two years now I’ve been working on agile Scrum teams as a technical information engineer (aka technical writer). I’ve moved through several emotional stages during this time: excitement, confidence, confusion, frustration, despair, acceptance, and back to confidence. I moved into that last stage of confidence while watching my tech info colleagues start their journeys on agile Scrum teams. As I look into their eyes, I see the confusion and frustration that once plagued my writer’s soul. Patting their backs in comfort and sympathy, I realize how far I’ve come in understanding and embracing the tech info role in agile. Fear not, I tell my colleagues. It’s not as bad as it looks. In fact, you’ll find it works out quite well!

What’s the Problem?
The first thing every writer asks about agile is, how does writing fit in? In agile, there is only one role for the average Scrum team member: Scrum team member. Whether you’re in development, QA, tech info, or usability, your role in agile is Scrum team member. The idea is that Scrum team members are not restricted by their job titles when developing a product. A team member can do development work one day and QA work the next, depending on the skill set and what work needs to be done at a given time.

It’s a good idea. But what does that mean for writers? Producing and managing technical content is a highly specialized skill. I can’t write code. I can’t create and run automated tests. And the fact is other team members can’t write and manage technical content.

What’s a Writer to Do?
Offering sympathies to my colleagues is all well and good, but I thought offering some useful suggestions might be more helpful. Take a deep breath and read on. Hopefully these tips will help pave the way to a successful start on a Scrum team.

Educate your team
I swear it’s true: Some people still think information engineers simply take content they are given and paste it into a Word document. A couple of weeks ago, a product owner actually told me that the developers provide the content and I just put it into the right format. I nearly required a defibrillator! It’s best to nip this kind of thinking in the bud. At the very beginning of a project, have a meeting with your Scrum team and major stakeholders. Show them exactly what you do.

  • Outline the initiatives and strategies that define your job.
  • Briefly describe tech info’s challenges.
  • Describe the steps you are taking to address those challenges and improve the customer documentation experience.
  • Talk about (and, if possible, demonstrate) potential documentation delivery methods.
  • Describe how content must be created and chunked so that it can be used in different ways.
  • Demonstrate your authoring tool. (See! It’s not Microsoft Word! Look at all these cool features!)

You don’t need to go into great depth in describing your tools and trade—let’s face it, the Scrum team and stakeholders are never going to actually use this information—but you want to provide them with enough context that they have a basic understanding of your role and the amount of effort required to perform your tasks.

Use the backlog
Track tech info stories in the backlog so both you and the rest of the team know what needs to be done. There are always things for tech info to do—usually many things—that only an information engineer can do. This can be building a bookshelf, versioning content, or rewriting existing content into scenarios or other documents, for example. Write these stories carefully so the team can understand what you are doing when they look at the story. Even if you are working on a “doc-only” story, you’re still part of a team, and you will be reporting on your progress at standup. Clearly state the done criteria so you can demonstrate your accomplishments at end-of-sprint review. Also be sure to maintain accurate estimates of the expected story sizes so you can fill up your personal velocity during sprint planning meetings.

Free your mind
Content management is a specialized gig. We’ve addressed that. But the truth is you are more than just a writer. While your tasks are more defined by your job title than they are for other Scrum team members, you aren’t completely removed from the process. For every story in every sprint, ask yourself how you can contribute to the end goal. The writing work is obvious, but just as other team members can help provide content for the documentation, you can also provide usability input, comment on wire frames, do some usability or manual QA testing, or perhaps manage compliance standards. The more you can step outside the tech info job, the more visible you are and, really, the more useful you are to the team. Don’t write yourself into a corner.

Manage your precious velocity
Managing velocity is a big part of sprint planning. This can be tricky for information engineers. You’ve already demonstrated during your education session that your role is unique, and for that reason you need to be more careful about managing your velocity on an individual level. If your scrum team consists of five full-time members with a total velocity of one hundred, to accurately fill up your personal time, you should hoard your estimated twenty velocity points as if they were the one true ring. Allocate your points appropriately for each story the team takes on, estimating the doc tasks—and the non-doc tasks that you can help with—as best you can. Normally, you’ll have time left over. Once you have populated the backlog with doc-only stories, you can browse through those stories and select enough work to fill up your precious velocity. Then you know how much you can reasonably commit to, and your colleagues see that you are participating as a full-time member of the Scrum team.

Pay attention and speak up—in that order
Nobody wants to look like an idiot. Chances are you are going to have to ask some questions during a sprint planning meeting, and you are sure to look like an idiot if you don’t ask smart questions at the right time because you have been focused on your laptop or phone. Meetings can be tedious, especially when you don’t understand what’s going on or when the discussion just doesn’t apply to what you do. But staying focused has two benefits: you learn new things, which allows you to eventually offer educated opinions about things unrelated to tech info; and the questions you ask will be more appropriate in timing and content. You will be—in perception and reality—a more valuable member of the team. It’s important that you understand what the doc requirements of a story are so that you can adequately judge the effort required and manage your individual velocity. You simply must speak up and ask questions in order to do your job well. Be smart about it.

Write later
The biggest challenge most writers see in agile is that things always change in a product as the development effort goes on, and if we document things as they’re being developed, we ultimately have to erase what we’ve written in prior sprints and rewrite it. And that’s true. It just is. What can I say? There are good reasons to have documentation happening alongside the development effort, such as being able to support incremental releases; but ultimately, it’s true that you’re going to have to do more writing when working as an agilist.

In order to maximize your efficiency, wait until as late as possible to document an active story. If your sprint work consists of two development stories that require some doc work and one doc-only story, focus entirely on the doc-only story at the beginning of the sprint while other team members work on the product development stories. Wait as long as you reasonably can before starting the doc work on those stories in the hopes that all the changes—for example, changes to button names—have already occurred. This is tricky because you don’t want to hold up a story, but the longer you wait, the greater the chance that you minimize the amount of doc revisions needed.

What Now?
Get started. You’ll stumble, but part of Scrum is inspecting and adapting. Consider these suggestions and use what makes sense. Agile takes into account that each situation is unique, and you need to determine what makes the most sense for your particular Scrum team. Use the retrospective to talk with team members and figure out how to refine your role and methods so you can be most effective and useful. Keep an open mind and a positive attitude—you might be surprised by just how well agile works for you.

User Comments

1 comment
Tim Thompson's picture

Being a tech writer on an agile team (although I mainly do QA) I find it helpful to first build the structure of the docs. Especially for help it is possible to first write the concept topics, then fill in the reference topics as the team goes along, and finally fill in the blanks of the task topics. The concepts are rather solid before development starts. The reference content such as validation messages and other potentially useful information comes up as the team works. The tasks are typically clear early on as well. On a CRUD page you have tasks for create, read, update, and delete. Creating those as empty shells and adding them to the help/docs is doable before the details are known. Often navigation is put in place first and may change only in regards to command texts, but not so much in functionality.

May 27, 2016 - 7:46am

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.