December 4, 2009

Agile Doc Reviews – The Documentation Sprint

Review discussion When I was working in a Waterfall development environment, the main documentation effort came at the end of the release cycle.  Sometimes the writers didn’t even start to receive team meeting invitations until the coding effort was well underway.  And by the time I needed documentation reviews, the product managers were often busy working on the next release.  On more than one occasion I had a PM give me a review comment about how a feature worked, and I had to show them that I was writing against the current code, while they were thinking about their design for the next release.

In an Agile environment, reviews for new features should be happening within the same Sprint as the development and testing.  But from what I’ve heard, that’s not always how it ends up working in practice.  There are Agile shops where the documentation happens a Sprint behind the development.  Which is still much quicker than in a Waterfall shop.

But what about major reviews?  Sprint reviews only cover the features being developed during a single Sprint.  At some point, the entire document or Help system needs to be reviewed for accuracy. For example, we’ve recently rewritten our installers.  So the entire Installation Guide has been rewritten and needs to be reviewed as a whole.  But we’ll also need to check the User Guide to make sure that we’re not referencing path names or files that no longer exist.

At some point in the cycle we need to plan time to concentrate on documentation reviews. I found my answer to the question of how to make this work before I had even really started as an Agile Technical Writer.  Last October, during my second week at my new job, I attended the DocTrain East conference in Boston.  [Unfortunately the company that put on the conference is a victim of the recent economic downturn and has closed their doors.]  One of the keynote speakers was Adam Hyde speaking on the topic “Read, Write, Remix: The FLOSS Manuals Story.”  This is what I wrote in my diary about his talk:

The other interesting idea that I got from his talk was that of a “documentation sprint.” Sometimes they gather 4 or 5 writers in one place (usually a nice hotel) and they’ll spend four days cranking out a manual. Since “sprint” is another Agile term, I wonder if I can talk the development team into doing one or two documentation sprints a year to help me crank out even more doc?

I took the idea right back to the office where I shared it with our VP of Engineering. The company had promised customers a new guide.  I’d been there less than a month and was still drinking from the fire hose, but hadn’t yet reached the point where the product made sense yet.  I wasn’t going to be able to deliver by the deadline by myself.  My VP loved the idea of a documentation sprint. In fact, within less than 24 hours of me mentioning the idea, he’s scheduled a meeting, we’d hashed out a general plan, and picked which week we were going to kick this off.  

During our planning discussion we’d joked about locking everyone in a conference room, ordering pizza and not letting them leave.  I said I’d dig out my official Hall Pass from my teaching days.  We ended up getting IT to set up computers in one of the conference rooms, and several of us sat and worked together during the week-long documentation Sprint. I mostly organized, formatted, and edited, which is not now I prefer to work. But since I hadn’t had time to learn the product,  I had to content myself with role-playing (rather convincingly, if I say so myself) a novice user who didn’t know anything about the product.

Our first doc sprint was a rousing success.  We went from blank page to released manual much quicker than I would have ever imagined possible.  One of the reasons why I think it was so successful was because management really got behind the idea.  Management made it clear to the developers that for a week, they were to concentrate on the doc.  And documentation reviews always succeed or fail based on management support.  If your managers don’t make it clear that reviewing the documentation is important, then reviewers don’t make it a priority.

As I like to remind people, we ship two things to the customers: software and documentation. Code needs to be tested, and documentation needs to be reviewed.

I anticipate that our next documentation sprint will be shortly before our next major release.  Scrum has enabled our developers to make some major changes to the product, and I’ve been making some major changes to the documentation set.  I want to make sure that the docs represent the current state of the product.

The FLOSS Manuals site has a book all about book sprints.

Anne Gentle blogs about doc sprints and other Agile techniques.



  1. […] Agile Doc Reviews – The Documentation Sprint (Julie Stickler) […]

    Pingback by Dew Drop – Weekend Edition – December 5-6, 2009 | Alvin Ashcraft's Morning Dew — December 5, 2009 @ 10:28 pm | Reply

  2. I love that you got buy-in for your book sprint! Just this morning I posted a guest post on The Agile Executive, talking about book sprints. http://theagileexecutive.com/2009/12/10/agile-across-the-enterprise-prioritizing-value-in-support-and-training-guest-post-by-anne-gentle/ I would have linked to your blog if I’d seen this a day before, but I guess that’s the power and speed of the bloggin’ web. 🙂 Thanks for posting.

    Comment by annegentle — December 10, 2009 @ 9:37 am | Reply

    • Thank you so much for the link! That is a great post. I’m going to add it to the post, in case people don’t click through to the comments.

      Comment by heratech — December 10, 2009 @ 8:07 pm | Reply

  3. This is a great story. It makes me want to go right out and try it.

    How did you keep the reviewers focused on the documentation and prevent them from getting sidetracked into designing the next release of the product?

    Comment by Larry Kunz — January 19, 2010 @ 5:18 pm | Reply

  4. […] Anne Gentle blogging about Agile Doc Reviews – The Documentation Sprint. […]

    Pingback by Planning a doc sprint « ffeathers — a technical writer’s blog — March 12, 2010 @ 3:39 pm | Reply

  5. […] and Community: The Social Web for Documentation. Julie Stickler blogged on HeraTech about Agile Doc Reviews – The Documentation Sprint. Janet Swisher writes “I suppose we’ll soon agree on a name for the era we’ve […]

    Pingback by AODC 2010 day 2: Engaging your readers in the documentation « ffeathers — a technical writer’s blog — June 12, 2010 @ 11:13 pm | Reply

  6. Hallo Julie

    Thanks again for such a great story about doc sprinting. As you know from our subsequent comment-swapping 🙂 I’ve also recently held a doc sprint. I’ve also given a couple of talks about doc sprints in the context of engaging readers in the documentation. So I thought you’d like to know that I’ve added your blog post as a reference in the slides of my recent AODC presentation on engaging readers in the documentation. My blog now has the slides and a summary of the session:

    Just a few days ago I gave a related presentation at the Atlassian Summit conference. I referred to your blog post in that talk too. The slides and video will be posted sometime soon on the Atlassian web site. I’ll blog about it when that happens.


    Comment by ffeathers — June 13, 2010 @ 1:04 am | Reply

RSS feed for comments on this post. TrackBack URI

Leave a Reply

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

WordPress.com Logo

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

Google photo

You are commenting using your Google 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

Create a free website or blog at WordPress.com.

%d bloggers like this: