Share This:

- By Michele Marques, Lead Information Developer, ITSM

 

A book sprint is when group of people get together to collaboratively write a book in a short period of time. Last month, I asked some questions about book sprints. Thanks to a great interview with Anne Gentle and Sarah Maddox, I have some answers to share with you.

 

Anne Gentle is a technical writer at OpenStack. Some of you might know Anne from when she had a technical communications blog at BMC Software or from her work on One Laptop Per Child (OLPC). Her current blog is http://justwriteclick.com/. Sarah Maddox is a technical writer with Atlassian. She blogs about doc sprints and other technical communications ideas at http://ffeathers.wordpress.com/.

 

Michele: Do you create new documents or update existing documents during a book sprint?

 

Anne: It really depends on the goals for the  sprint. We've done both with FLOSS Manuals, either creating a new manual  from nothing (though we agree to an outline in the sprint planning  phase) or updating an existing manual when a software version release  revs upward.

 

Sarah: We've held two doc sprints so far, one focusing on tutorials for developers and the other focusing on quick-start guides for users of our products. In both cases, the main aim was to write new documents. In both doc sprints, however, some of the sprinters decided that it would be more valuable to tackle existing reference documentation that was out of date. They reported that they found this a very satisfying experience. One of them even said, "The biggest sign of victory is how many pages I managed to delete."

 

Michele: How many documents do you typically create (or update) during a book sprint?

 

Anne: If it's a week-long sprint, you can create a 200+ page book  with a team of less than 10 writers. Usually a doc sprint is a focused  effort so it's mostly a single document or website or software release  that you'd work on.

 

Sarah: For our first doc sprint, we created 19 new tutorials on how to develop gadgets and plugins. In the second doc sprint we wrote 25 new guides consisting of around 42 pages. In both sprints we also updated a number of the existing reference documents, but I don't have the numbers for those.

 

Michele: How long does a book sprint last?

 

Anne: Anywhere from a day to a week.

 

Sarah: Our first doc sprint was three days long. That worked really well. We made the second one shorter, only two days, because we thought it would be easier for people if they did not have to request so much time to commit to what is after all "just" documentation. In hindsight though, three days is a better period. It was hard to fit everything into two days, especially when you need a kickoff meeting at the beginning and a retrospective and demo session at the end. Also, in our case many of the sprinters were working remotely and in different time zones. That meant that our time zones coincided just once over the two-day period whereas over three days we had more chance to collaborate across continents.

 

Michele: How many people work on documents during the book sprint?

 

Anne: For the OLPC book sprint we had 8 people in the room most  days but probably a dozen were in and out with 2 people working remotely  on bite-sized tasks like taking photos for demonstration purposes (how  to insert and remove a memory card).

 

Sarah: We had around 20 people in the first sprint and 30 in the second. There were two main locations, one in San Francisco and one in Sydney. Quite a few people worked remotely, included one person in Moscow and one in Israel.

Here's our "hall of fame", showing the participants in our doc sprint with photos and distinguishing features:
http://confluence.atlassian.com/display/DOCSPRINT/Doc+Sprint+Hall+of+Fame

 


Michele: Who participates in the book sprint? And what are their roles?

 

Anne: Ideally you'll have a sprint coordinator and if you're  really lucky that person works on coordination and doesn't have to  write. That person makes sure assignments are doled out and that people  can get unstuck if they can't get information they need or if they have  problems with the tool set. You also want a logistics planner to ensure  meals are provided and some sort of activities are available for the  writers. If that person is local and familiar with the area, all the  better. See also http://en.flossmanuals.net/BookSprints/Roles.

 

Sarah: We invited people from both within the company and from outside - customers, community developers, technical writers and developers who have an interest in our products or our documentation. For the first doc sprint, most people were developers. For the second, we had support engineers, technical sales engineers, business analysts, technical writers and all sorts.

 

 

Michele: If you have non-writers writing - how does that work? And how do you encourage them to participate?

 

Anne: [How does it work?] In the case of OLPC, it  really depended on the person. For example, Walter Bender, founder of  MIT labs and a software director wasn't really a "writer" as his job  title but he could write really well and is a published author. For  OpenStack, all my participants are developers because I'm the only  writer for the project, but they were happy to set aside time for  documentation because it's an important step to meet our goal of  increasing OpenStack adoption.


[How do you encourage them to participate?] Other  people who are non-writers may have a tough time getting started, so  assignments and narrowing their scope is important. For examples of  non-writing tasks that are valuable and necessary, have them test  procedures, edit what's already written, or write CSS or JavaScript to  add a particular feature to your documentation.

 

Sarah: We had people from all sorts of roles taking part. I think that this is one of the most valuable aspects of a doc sprint. It gives other people a chance to get intimate with the documentation, and it gives the technical writers a great insight into what other people think of the documentation and what they'd like to see improved. All sprinters were keen to work with us, seeing us both as representatives of the technical writing team and as representatives of our company. When planning the doc sprint, we searched for people who had shown an interest in the documentation and wrote to each one personally, asking if they'd be interested in taking part in a doc sprint. We also blogged about the sprint, letting people know that everyone is welcome. It goes without saying, of course, that we promised them chocolate.

We did expect a bit of push back, and perhaps that some developers might moan about spending three days doing documentation. But that was not the case at all. We were surprised and delighted to see the value people put on the documentation and the pride of ownership they feel in it. All of them said that they had enjoyed the doc sprint and that we should do it again.

 

Michele: How do you prepare for a book sprint?

 

Anne: Planning is the under-the-water iceberg of a book sprint.  You have to get participants, and the right mix of participants, choose a  location, find sponsors as needed, agree to an outline, and so on. See http://en.flossmanuals.net/BookSprints/Process.

 

Sarah: Oh, that's a big one. I think there's too much to say in just a paragraph or two. I've written a blog post about it, which may be helpful. The post also links to a number of other resources that help with the planning:
http://ffeathers.wordpress.com/2010/03/13/planning-a-doc-sprint/

I think the two most important things are: Get started early (about two months before the sprint) and get other people involved early, because they will have great ideas to help make your doc sprint special.

Another thing is to remember the "fun" aspect. We held chocolate haiku competitions, chocolate blind taste tests and various other activities to give people an outlet when their brains were fried from too much documentation.

 

Michele: After you complete a book sprint, what's left to prepare the documentation for publication?

 

Anne: For FLOSS manuals, we print on the last day of the  sprint and upload a print-ready PDF to Lulu.com for production so that  people can order it right away. There may be additional editing but  ideally you have a book at the end of the sprint. For OpenStack, we have  a merging process that must occur for the documentation to display on  the website.

 

Sarah: That's a very good question. I think a lot depends on the type of documents you target in the sprint, and the writers taking part. Another big factor is the templates and style guides that you provide. After our first doc sprint, two of us spent approximately two weeks finalising the tutorials. Ben, a developer, did a technical review while I did the technical writer's review and placed the tutorials into the context of the rest of the documentation. Our second sprint had a more open-ended focus. We did not supply templates and had very few guidelines, because we wanted to give people more scope to experiment. There were also more writers and we produced more guides. This sprint took place this month, and we have not yet reviewed and incorporated the documents into the main product documentation.

 

Michele: What's the best thing about book sprints?

 

Anne: For me, it's the time set aside to collaborate in a room together and getting to know people better.

 

Sarah: The people. In both our sprints, I've been amazed and grateful at the dedication and skill that all the sprinters bring to their work, and totally delighted by the new perspectives they give me and our documentation.

 

Michele: What's the worst thing about book sprints?

 

Anne: They are very, very draining and rather nerve-wracking if expectations are high.

 

Sarah: That we can't hold more of them. I think they are very valuable to our company, our documentation, our writers and our customers. They do, however, demand a lot of time from us as organisers and from the sprinters who have to take away time from their day jobs. I wish we could do them more often!

 

Michele: What would you do differently in your next book sprint?

 

Anne: I really want to plan a week-long book sprint for  OpenStack, but our last one was just a day. There must be something in  the middle that would work well too. I want to involve one of our  fledgling user groups in a book sprint if possible.

 

Sarah: One of the most interesting comments we received after our sprint was that the other sprinters wished they'd been able to spend more time with the technical writers. Each of us technical writers had assigned ourselves a document to write during the sprint, assuming that that would be the best use of our time. Instead, people would have liked to collaborate with one of us for a couple of hours each day, so that we could help them with their own projects. In the next doc sprint, we may decide not to plan any writing projects for ourselves but instead to offer a schedule where people can "pair" with a technical writer as often as they like. People said they knew what they wanted to write about but were having trouble getting started, structuring their documents or just "finding the right words". It was great to see how much they value our skills.

 

Michele: Is there anything else you want to add?

 


Anne: For a doc sprint just 2 weeks ago with  OpenStack, we also had a group collaboration session for an easy-to-use  "demo" of OpenStack which involves user experience. I'm pretty excited  to think about possibilities of not just doc sprints but doc+ux sprints.  The goals and results are tightly coupled.

 

Sarah: We found it very useful to plan a demonstration session at the end of the sprint, and to tell people at the start that this would happen. It gave a good focus to the two or three days, because people knew that they'd need to strut their stuff to the rest of the group at the end. It was also very useful, interesting and productive to hold a short retrospective session at the end of the last day, where sprinters could tell us what they think went well and what we could have done better.

Here is the feedback from our most recent retrospective:
http://confluence.atlassian.com/display/DOCSPRINT/Doc+Sprint+Retrospective+-+November+2010

I guess the most interesting thing about a doc sprint it that it has so many "hidden" purposes and so many benefits, only one of which is to get the documents written. From my point of view, perhaps the greatest purpose and benefit is to get other people involved in and engaged in the documentation - both people within your own company and outsiders too. Let the world know what technical writers do and how awesome we are!

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.