How does Agile affect documentation?

Here's the rub for technical writers: Converting to Agile methods forces changes to how we create and manage documentation. In our case, documentation is supposed to be handled "like code" within the Scrum/sprint process, subject to the same requirements. So, here are the implications we deal with:

• No lagging a sprint behind, as some shops do; we must be "shippable" at Review.
  • We write up new documentation and revise the existing at the same time as it's being coded and tested.
  • Within the sprint, there's a bit of a waterfall, just as exists for testers: we can't see what's not coded yet. Ends of sprints are quite brisk for writers.
• We focus on continuous, automated builds, in support of being ready-to-ship.
  • Our build engineers worked hard to create a continuous, automated build environment to support Agile, meaning that checking in code triggers an immediate rebuild. The rebuild success or failure is broadcast throughout Production, reporting errors and test failure details, for immediate response.
  • Continuous integration builds allow testers and writers to always work with "real" builds.
  • Automated builds of documentation into Help sites and manuals mimicks this system, and it allows testers to evaluate documentation based on what will actually ship.
  • In reviews, we provide links to the actual, finished documentation changes.
• Docs are part of Definition of Done; incomplete doc tasks block the entire team.
  • Tempting as it would be to push incomplete doc tasks to the following sprint, we don't show any stories as complete if the docs aren't there.
  • To keep the tech writer (a shared resource) from blocking the team's ability to complete, other team members must be able to update doc source.
• Integration and overall review of release documentation happens during final regression sprints.
  • Editing for document flow and consistency is largely deferred until the very end, by necessity. The more cooks in the kitchen, content-wise, the more daunting this is.
  • Final regression before a general release is the only opportunity to force teams and stakeholders to review entire documents, versus the single topics affected by a given sprint.
  • All production work (new batch scripts, archiving, setting up manuals with printers, updating publication sites) also happens during this period, so the documentation team is very crunched at a time when the rest of production experiences a relatively restful break from typical sprint work.

Since a goal of Agile is to have teams work productively at an even, sustainable pace, I see real challenges in this approach to documentation: to avoid a train wreck during regression, I suspect the integration and editing functions need to be performed continuously throughout the entire release. I think this argues for placing technical editing in a supporting function outside of the teams, with an Editorial Review required within Definition of Done for any doc tasks. Do any of you manage it this way?

Comments

[Sarah Maddox]

Hallo Mary

Thanks for a great post. It's very interesting to my in particular right now. We're planning to integrate our tech writing tasks more closely into the various agile teams where I work.

Coincidentally, today I published my notes on an introductory session to agile methodologies that I attended this week. It may be a good starting point for people who want to learn more about agile processes and principles before going into the details of your post. HEre it is, for people who are interested:
http://ffeathers.wordpress.com/2011/02/26/introduction-to-agile-methodologies/

I have updated my post to link to yours too. :)

Cheers
Sarah

[Mary Connor]

Thanks much, Sarah! Your post is a terrific introduction to the whole approach, with its mass of new concepts and terminology. When we first switched to Agile methods, I was hard-pressed to find ANY information specific to user/product documentation -- it was all debate about development process documentation (artifacts).

My next posts will explain how/why we migrated our documentation tools and processes to support the new method. I'll be presenting on that at CM Strategies 2011 (cm-strategies.com).

[Felicity]

It's great to hear about other writers working with Agile development teams.

In my team we started trying Agile about a year ago. We consider the documentation to be part of each development user story and this has resulted in huge improvements to my working environment. I now know exactly what's going on all the time and can work on updating Help and documentation throughout the development cycle. Previously, there was a management idea that with a year long development cycle there was no need for technical writing for the first four-six months. This gave me a very bumpy work-load with a frantic panic to avoid delaying the release. We have yet to release under Agile, but it ought to be better as I've been able to work with the developers throughout. There will be no last minute realisations that something a developer tweaked months ago actually does have an impact on the Help.

We also have documentation user stories for documents which are not directly related to a development story but are still important (e.g. installation guide or demo video for a new product). These are reviewed within the iteration.

[Mary Connor]

That last point is critical: having user stories for the information deliverables that need to be done outside of code development. I think part of the problem in our case is that we don't have a product owner with jurisdiction over these deliverables. How does your shop handle that?

[Felicity]

We're a very small company with 6 developers, 1 QA and 1 tech author. Currently we use the CTO as Product Owner since he has the best view of what the customers want. However, I am allowed to create user stories for any documentation that I think needs to be delivered. These get scheduled when I'm not too swamped with Help/documentation for the developer user stories. The Produce Owner still has control over their priority but I can raise whatever is required.