Writing in an Agile World


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.