Planning a doc sprint
We held our first doc sprint a few weeks ago, and it was awesome. Even the moderately stressed organiser (that’s me, folks) had a lot of fun! We wrote some very shiny tutorials. My earlier post was about the people and the results, so now I thought you might like to hear about the planning and organisation that went into the doc sprint. All the stuff we learned. In case you’re thinking of doing one yourself.
A “doc sprint” is similar to a book sprint. We called ours a doc sprint because it focused on technical documentation and on developing a set of tutorials, rather than a single book. We invited a number of developers to join the technical writing team in a three-day sprint, with the aim of producing some quality tutorials on gadget and plugin development.
Update on 12 September 2012: I’ve published a new post about running a doc sprint, with lessons learned from the last few sprints we’ve run: How to plan a doc sprint. Maybe you’d like to glance through the post below, and then move to the more recent one.
Are ya ready? I feel a mega post coming on.😉
What did we get up to during the doc sprint?
We shut ourselves up in a room, told everyone else to keep away because this was documentation quality time, and wrote like maniacs. We also ate chocolate, composed haikus when our brains needed a break, bombarded Google Talk with inanities and held “remote standups” via webinars.
Why remote standups? Because we had 20-odd sprinters in Sydney, 2 in San Francisco and 2 somewhere else entirely. We flew 2 sprinters in to Sydney from our San Francisco office and generally mixed things up. The sprinters are all in our Doc Sprint Hall of Fame.
Two people even joined us a week late. We figured out how to do remote standups but alas, we haven’t yet managed time-travelling standups.🙂 That said, the wiki does a fair approximation. All our content is still there. The two tardy sprinters just grabbed a template and got going.
When to start planning
Early. We started planning in early November, for a sprint scheduled for mid February. That gave us three months to get our ducks in a row. I’m guessing that we won’t need as much time to plan the next sprint, but certainly the first takes a lot of thinking and planning.
In our case, we wanted to invite people to travel from the United States to Australia, so we needed to give them plenty of warning and we needed to get budgetary approval from management. We were also not sure how many external sprinters we’d have. By “external”, I mean people who are not Atlassian employees. (Atlassian is the company I work for.)
Involving your team and management
One of the greatest things I found is just how enthusiastic, generous and inventive people are when given an idea to play with. My advice is definitely to get your team involved as soon as you can. Start a wiki page or a Google Doc, hold a kickoff meeting and throw around some chocolate. The ideas will start flooding in! I wrote about the people in my previous post, but it’s worth mentioning here again:
The people are the best part of a doc sprint.
Setting up a wishlist of documents
I wanted to give people something to get to grips with, so that they knew what they would be doing if they signed up for the sprint. I figured it would give them more impetus to join the sprint and it would get the first day of the sprint itself off to a running start. I also wanted people to feel that they could add their own ideas about what documents we needed.
We started by defining the focus of this particular sprint: tutorials on how to develop plugins and gadgets for the Atlassian applications.
I created a wiki page on our intranet wiki, seeded it with a basic list of tutorials that I thought we needed and asked Atlassians for input. After a few weeks we had a good if somewhat unfocused list. Next I chatted to our CEOs and other leaders get their input. Finally we held a brainstorm meeting to hone the list down to a good size and to make sure each tutorial covered a single topic. (Well, more or less. That was the idea, anyway.)
Next, I put the tutorial wishlist on the public wiki and invited the whole wide world to look at and update it. In practice, the “whole wide world” is the community developers, partners and doc sprint invitees.
We also suggested to the doc sprint invitees that they put their names down next to the tutorials that they would like to develop. If they wished, they could partner with another developer on the same tutorial. Doc sprint pairing for the win!
The resulting tutorial wishlist gave everyone a focus. Come the first morning of the sprint, many people dived right in without even waiting for the kickoff meeting.
It works well to map out a plan of the blogs, emails and other communications that you’ll send before, during and after the sprint. When things hot up, it’s all too easy to forget to send the final reminders or even to kick off the first webinar! A communication plan also helps to make sure you don’t spam people at some times and then leave them in the dark at other times.
The communication plan can be very simple. Here’s what ours looks like:
Have a good think about who to ask. Do you want to involve people outside your organisation, such as community developers, community authors, or partners? Maybe you want to limit the sprint to internal developers. Decide if you want to look outside your team, and whether you’re inviting technical writers only, or developers, or all sorts.
When should you send the invitations? If you’re planning to invite people to fly in from other cities, I think two months is a good time frame. For people who are in the same office as you, or people who intend to work remotely, then one month is OK. After all, which of us knows now whether we’ll actually be free to contribute to a doc sprint in two months’ time?
I sent out invitations in the form of blog posts like this one, as well as personal email messages to known members of the developer community. When the sprint date drew close, I sent out a reminder blog post and email messages.
I also tweeted copiously about the sprint. After all, it was a big event in my working life and in my team’s life too.
Why do people take part in a doc sprint?
What motivates people to give their time and skills in a doc sprint? Before composing the basic text of the invitations, I had a good read of this study on why people are willing to contribute their time to community documentation projects: Why do people write free documentation? Ours is not exactly free documentation, but I think the same sort of motivations apply. (Basically, people are just awesome.)
People enjoy learning cool stuff from the other experts on the sprint. External developers enjoy the contact with Atlassians, and Atlassians enjoy and learn from the external developers who are using our tools. People like helping other people. They get a sense of satisfaction from fixing documentation that is out of date and from developing a new tutorial that is as near perfect as possible.
One of the external attendees mentioned that the personal email invitations were very powerful. If you already know some of the people you are inviting, or know something about their previous and ongoing contributions to or questions about the documentation and code, then it’s really nice to put that in the email message. It makes sure that you think about the person you’re writing to. They can see that when they read the invitation.
Templates and style guide
We already had a style guide and I included mention of it in the invitations. But to be honest, I don’t know that many people paid attention. It’s probably too much information.
Templates, on the other hand, were extremely useful. They got people up and running quickly (reduced the fear factor) and they give a basic framework that is standard across all the tutorials. I created a template for each type of tutorial we were planning to write:
- Template for plugin tutorials
- Template for standalone gadget tutorials
- Template for plugin gadget tutorials
During the course of the doc sprint, people suggested additions and improvements to the templates. I applied the updates on the spot, and let all the sprinters know. In some cases, we needed to apply the updates to some of the tutorials after the sprint, because the template updates were too late for people to take into account. That’s cool. The main thing was to get the tutorials written and as perfect as possible during the sprint. It’s a bonus that we now have improved templates for use in another sprint and indeed in day-to-day document authoring.
Wiki or web page visible to outsiders
It’s very useful if you can publish details of your doc sprint to outsiders, and even more useful if you can allow all comers to update the information. We have a tame Confluence wiki, so we created a Doc Sprint space and opened up the permissions of that space so that all logged-in users can edit the pages. That meant that would-be attendees could simply add themselves to the list and put their names down next to the tutorials they fancied. They even added suggestions to the tutorial wishlist. This helped people to feel involved immediately, long before the sprint started.
We also published a schedule showing the activities day by day. At first the schedule and other information on the wiki was a bit bare. We fleshed it out as the sprint date drew closer. (LOL, I see that the schedule page still announces that it’s not yet final. That’s agile for you!) The schedule shows the activities day by day, split by time zone, including the webinars, meals, fun activities, show and tell, retrospectives and so on.
For us, a good set of online communication tools was essential because we had sprinters in different countries and different time zones. Even if you’re all in one room, though, I think an online chat group and a wiki are indispensible.
Ed set up the online group, chat room and webinars for our sprint:
- A Google Group, so that we could sent emails to all sprinters.
- An online chat room using Tea Party, which we accessed primarily through Google Talk. Note that some people said they would prefer IRC or Jabber conference.
- A series of webinars (online conference meetings) hosted by GoToMeeting.
The webinar sessions worked very well. We used them to kick off the sprint, to take the place of standups during the sprint, and to conduct the final presentation and retrospective for the remote sprinters. For the daily webinar, we kept to the same format as standups (meetings held standing up, a mainstay of agile development). Each sprinter said what they had done so far and what they were planning next.
Just as in a standup, this led to useful interactions. For example, Daniel (in Sydney) mentioned an error that he had encountered while developing a JIRA plugin. Matt (in San Francisco) said he was interested, and later got the details from Daniel to include in his sprint document about common error messages when writing JIRA plugins.
Hint: Schedule a practice webinar before the sprint starts, so that you can get to know the webinar software.
Write up a plan for the first webinar, which is in effect the kickoff meeting. Our webinar agenda included such things as introducing the sprint, asking people to introduce themselves, showing people the templates, explaining the format and logistics of the sprint, and so on.
We also made sure we had a development environment set up. In our case, people needed to write code as well as documents, so we needed a source control repository and a continuous integration server that will run their tests. The documents themselves were fairly easy: we put them into the doc sprint wiki space. We had already set the permissions in this space to allow any logged-in user to add and edit pages.
Here’s an extract from our online chat group. Check out the mishmash of technical and fun stuff comments. Could make a good rap song, I reckon.
Catering, venue and other practicalities
There are a lot of practicalities to consider: Mundane things like tables, chairs, network hubs and signs telling people where to go.
It’s useful to tell people what they need to bring. In particular, they’ll probably need to bring their own laptop computers.
Find out what your budget is. Will the company or the sprint organisers pay for any meals? Then let the sprinters know, so that they can decide what to do about their meals. If you’re taking people out for dinner on the last day, or any other occasion, don’t forget to book a table in a restaurant.
We had a long list of tasks on the planning wiki page, with a person’s name next to each task. I added even simple tasks like booking the restaurant into the plan, because I knew I was likely to be in a tizzy and forget to book. Think of the satisfaction you’ll have as you tick off each task.
Theme and fun
A theme is great for making a doc sprint sound like fun, giving it and the sprinters a sense of unity, and just plain prettying up the wiki pages!
We agonised for a number of days about choosing our theme. What could it be? Something to do with the Hitchhiker’s Guide to the Galaxy? A sports car or running theme, to fit with the word “sprint”? The one and only theme occurred to me in that most inspirational of places — the E66 bus on my way home one evening:
Chocolate, of course!
Once we had a theme, Andrew could perfect his ideas for fun stuff.
Another tip: Don’t forget to organise some cameras! I pestered the remote participants to take photos of themselves too, so that we could include them in the Hall of Fame.
The most important task
Most important of all was, of course, to buy the chocolate. For this task you need exquisite timing combined with impeccable taste. We had asked our sprinters to pick a chocolate-related middle name. Unbeknownst to the sprinters (and unbeknownst to us too, until Ed thought up the idea much later), we would give each participant their “name chocolate” at the sprint. Here are a few of the names people chose:
- Rich “90% Cocoa” Wallace – Some people are serious about their chocolate.
- Jonathan “Choco Taco” Doklovic – Jonathan was a remote participant. I’d never heard of Choco Tacos, but they look like a suitably decadent treat for a technical writer. Alas, I had to persuade Jonathan, reluctantly, that it wasn’t practical to post a Choco Taco to him and we sent an Amano Ocumare chocolate bar instead. I hope it was at least as good!
- Andreas “Ferrero Rocher” Knecht – I love the way this name rolls off the tongue.
- Ben “Smarties” Speakmon – Ben, a San Franciscan, had heard that Smarties in Australia are quite different from Smarties in the US. He flew in to Sydney for the doc sprint, toting a huge bag of American Smarties. We gave him a box of Ozzie Smarties. A large part of the first webinar was taken up in exclaiming over the differences.
- Erik “Chocolate Salty Balls” van Zijst – Don’t even go there.
Here’s part of the haul after I went shopping:
Presentations (show and tell)
We scheduled the doc sprint presentations for 3pm on the last day. Everyone knew that at 2pm, they needed to down tools and concentrate on getting their presentations in order. We decided to keep it simple: each person had 3 minutes to walk through their tutorial, explaining its purpose and its cool flashy parts.
Having a deadline like this was a great motivator. It gave everyone something to work towards, and finished the sprint with a bang.
We also held a couple of retrospective sessions, to get feedback and suggestions from attendees, to hear what they thought went well and so that we can do things better next time. Giles organised a very efficient and thorough process, using the wiki to gather comments from all attendees scattered across the globe. In Sydney we met with all sprinters immediately after the presentations, to go through the comments in detail, adding more suggestions as we went along. Then we held a webinar session to do the same with the San Francisco sprinters and anyone else who could attend.
Giles then summarised the results and published them on the wiki.
Flexibility in the planning
All the planning paid off very well. But it’s also worth knowing that people changed their plans a fair bit during the first day. It was agile at its best. We started with the tutorial wishlist, and most people had a tutorial already assigned to them. But then they found problems with the SDK (plugin software development kit) or things that would take too long or be otherwise impractical for either the tutorial or the sprint. Some people discovered that it would be more efficient if they paired with another developer on a different tutorial. Some people decided that the reference documentation needed more tender loving care than a new tutorial.
The thing is, we had the experts in the room and it was just great to have them looking at the documentation, deciding what needed doing, and then doing it. This is what the sprint was all about. We just gave them the opportunity to do it.
How much sprinting can you do if you’re the organiser too?
This is a really useful thing I learned! If you, as organiser, are planning to develop any new documents or tutorials yourself during the sprint, make sure you assign yourself something simple and short. You will be very busy, even during the sprint. People will come to you with all sorts of “interesting” questions – ranging from bugs in the SDK (software development kit) to where to go for lunch and where’s the fan that should have arrived yesterday! You need to feel free to devote time to things like updating templates, telling people what’s happening, taking photos and writing notes for the post-sprint blogs.
I chose to develop a really simple tutorial because I guessed I wouldn’t have time for much else during the sprint. Phew, I was right!
I think it’s important to acknowledge the great work people have done. They have contributed a lot of time and expertise on something that isn’t their day job. Some of the rewards are inherent in the doc sprint itself, such as learning cool stuff from the other experts, having contact with external and internal developers, helping others, and developing a satisfyingly perfect tutorial. Even so, it’s enjoyable and nice to recognise people’s contributions.
We created a Doc Sprint Hall of Fame, showing all participants with the tutorials they wrote and a photograph taken during the sprint. I’ve also written a few blogs, on the Atlassian blog as well as here on ffeathers, mentioning the great work people have done.
There’s not much more we can do, really, apart from promise the sprinters that they’ll be first on the list for our next doc sprint.🙂
Inevitably there will be a bit of tidying up in the tutorials themselves. We put ours through a technical review, and we also intend to do a technical writing review as soon as time allows. We’ve also moved them from the “Doc Sprint” space on the wiki into the Developer Network space along with the other tutorials.
Here’s a collection of good resources and ideas:
- Anne Gentle‘s book, Conversation and Community, has plenty of information about book sprints. It’s a great book, and a must read. Here’s my review of the book, and here’s the book’s web page on XML Press.
- The Book Sprint Central is a good introduction to the why’s and wherefores.
- The book about book sprints on the FLOSS Manuals site.
- Google’s report of the Ogg Theora Book Sprint.
- Andy Oram on the Challenges from a book sprint: the great things about ignorance and disorder.
- squeakland’s report of their first book sprint, to write an the Etoys Reference Manual.
- Julie Stickler blogging about Agile Doc Reviews – The Documentation Sprint.
In a nutshell
Are you thinking of doing a doc sprint? Go for it. It’s great! Let me know how it goes, or if you have any questions that I may be able to help with.🙂
Posted on 13 March 2010, in atlassian, technical writing and tagged agile, agile methodology, agile technical writing, atlassian, book sprint, chocolate, doc sprint, technical documentation, technical writing. Bookmark the permalink. 15 Comments.