Information development flexibility in Agile at STC Summit 2013

This week I’m attending STC Summit 2013, the annual conference of the Society for Technical Communication. I’ll blog about the sessions I attend, and give you some links to other news I hear about too. You’ll find my posts under the tag stc13 on this blog.

It’s bright and early on Monday morning. Alyssa Fox is kicking off with a session titled Bending Without Breaking: Info Dev Flexibility in Agile. She has made her presentation available on SlideShare. Here’s the blurb:

This session helps technical communicators face challenges in agile planning and execution. It’s increasingly common for writers to work on multiple agile teams. The session includes tips for better communication and teamwork on your agile team, with the goal of a “whole team approach” in mind.

The old way and the new way

Alyssa explained that initially in her organisation, the functional areas were split: the developers, QE (quality engineers), ID (information developers, or technical writers) and other members of a product development team worked separately on their own tasks.

Later, they moved to the “whole team” approach, which means all members of the team accept responsibility for delivering all aspects of the user story. QE, technical writers, developers, and all. Everyone accepts that all aspects of the user story, including documentation, must be complete in order to declare the sprint complete.

How to get to the new state

There are a number of ways to get to that happy state. These are the ones I noted while Alyssa was speaking:

  • All developers do their own unit testing.
  • Automated testing is also essential.
  • QE and information development must be included in all estimates. If you don’t do that, it will not be possible to meet your targets.
  • Make sure you fix all bugs within the sprint in which they were created.
  • Help other functional areas to complete their tasks, when you’ve finished yours. For example, you can help with usability testing, setting up environments, grooming the backlog of tasks.


To ensure the info dev team can successfully become a useful and productive part of an agile team, you need to give them support by adapting the processes of the agile team.

When setting up user stories, do them in vertical slices rather than horizontal. In other words, make sure all functional areas are covered during a single sprint. This means you can have something potentially shippable by the end of the sprint.

Feature testing, regression testing and documentation therefore happen during the sprint. If you have a testing crunch or a doc crunch at the end of the sprint, it means the team as a whole is doing something wrong. This requires the discipline where all members of team know what is required of them.

(I looked up “swarming” after Alyssa’s talk. It’s the practise where an agile team focuses all its effort on one story at a time, where practical.)

Release planning

The way you plan a release has a big impact on the success of the release. A release consists of a number of sprints, culminating in a marketable release to present to customers.

Have a backlog of user stories to pull your sprint tasks from. Make sure the user stories are well estimated. Define a theme for the release, then pick stories that fit into that theme. Take the velocity of the team into account.

Before you start, make sure you have a good idea of the stories you will tackle in the first two to three sprints, and have all the stories for the first sprint clearly defined.

Document review cycles

Alyssa recommends that you plan for two to three drafts of each document: a first draft, an approval draft, and a quality edit draft. Get the SMEs to review the first draft during the sprint.

Creating user stories

This is the most vital part of ensuring success for information development. You need good user stories so the info dev team can plan and draft the documentation.

User stories must focus on the user’s point of view. Ensure you prioritise those of the highest value to the customers.

Making user stories focus on the user

There are three parts to a user story:

  • Problem statement. This is the most essential part of the user story. Usually, the developer writes the problem statement. Info dev can add tremendous benefit by helping to refine the problem statement.
  • Acceptance criteria. This is essential to know how the users can know that the problem is solved. Again, the developers start by writing this part, and the technical writers add value by reviewing it.
  • Acceptance tests. These form the technical way of testing that the problem is fixed. Info dev typically doesn’t have much input here.

Thanks to the info dev involvement in defining the problem and the acceptance criteria, it is much easier for the writerss to start the documentation and release notes.

More advantages of this approach

It gets everyone on the same page. Everyone knows what the problem is and how we can know when it’s done.

It eliminates unnecessary ad hoc testing and reveals possibilities for user testing.

It forces everyone to think about the user’s side of things and the user impact of the planned changes. Writing a user story may make you realise the problem actually isn’t such a great problem, and it would be a waste to spend effort on it.

It gives the product manager a sense of security that the team understands the requirements.

Backlog grooming

Backlog grooming is the process of looking through the stories in the backlog, analysing, estimating and prioritising them. You should do your backlog grooming frequently. For example, once a week or at the beginning of each sprint.

Alyssa discussed the technique of “planning poker”. The idea is to discuss the stories and estimate the effort using story points for all functional areas. Make sure the user stories at the top of the backlog are small enough to complete in a single sprint.

It’s important that all team members, or at least the leads from each functional area, are involved in this exercise.

Sprint planning

Create your sprint backlog by pulling stories from the product backlog into the sprint backlog. Estimate the tasks in hours, and remember to include time for overhead (meetings, technical setup, admin, etc). Make sure your estimate fits your capacity for the project and the sprint. This is particularly important for people working on multiple projects, as so many technical writers do. Book yourself for the number of hours you have available, and no more.

Allyssa recommends planning 20-25% of each writer’s time for vacation and non-sprint responsibilities. She says we should exclude the last day of the sprint from our planning.

Make sure the development finishes before the end of the sprint, to give testing and info dev time to complete their tasks too.

The writers on Alyssa’s team maintain spreadsheets showing their capacity (in hours) across the various projects.

Coping with multiple projects and meetings

If you’re on multiple projects, you can’t attend all meetings. You’d never get your work done. Think about attending one or two scrum meetings per week instead of all of them, and prioritise the ones that are the most important to you. Ask the scrum master to send status emails for the meetings, so you can catch up on what you miss.

Be pushy. Make your presence and needs known. You need to make sure the team knows you need the information. Alyssa has put together a list of criteria to help development teams know when info dev needs to be involved. For example, when the development team is ready to start coding. Then they hold a team kickoff meeting, so that the info dev team can decide when they need to start work on the project.

What does “potentially shippable” mean?

A document should be shippable for that part of the product developed during the sprint. The documentation for that part of the product needs to be ready. This includes the topics, videos, and other material required, but not the whole book or whole help system.

Tasks such as an approval draft of the whole document, final reviews, the production process, and the release notes, are delivered at the end of the release. They don’t need to be part of the sprint delivery.

More topics arising from questions

There were a number of questions from the audience.

How do you handle translation? Alyssa’s team fits this into their milestones. They give the translators 90% of everything towards the end of the release. They make sure all the English-language stuff is ready to go by release date, and deliver the rest later. All their documentaiton is online.

What is the typical sprint length in Alyssa’s organisation? Sprint length is three weeks for most teams. This works best. Some teams have shorter sprints, but those are difficult to work with.

How hard was it to get all the development teams to follow the same process? Some of them find this difficult. In the early days, some teams were using different processes. This was very difficult for the teams working on multiple projects, like QA and infro dev. Support from upper management is essential, to get agreement from all teams.

How do you handle changes in the software resulting from user feedback? It’s a good idea to build in buffers when doing your estimates, because you may need to make changes as a result of customer feedback. Being able to change is built into agile.

Alyssa mentioned the concept of “targeted” documentation, which focuses more on conceptual documentation rather than “how to” guides. It comes from the perspective of “how do I do my job with this product” rather than “how do I use this product”. Alyssa’s team don’t document everything, but spend time analysing what’s needed. If something is obvious from the UI, they don’t document it. If they get feedback from customers that they need the documentation that has been left out, then they consider adding it.

What source material is available on doing info dev in an agile environment? Alyssa says there’s not a lot available. There are blogs, but there’s a lot to say and not a lot of information yet. It’s been mostly trial and error for her team.

Thanks Alyssa

Alyssa spoke engagingly and passionately, and covered a complex topic with aplomb. Someone in the audience suggested she write a book. I second that suggestion!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 7 May 2013, in STC, technical writing and tagged . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: