How to plan a doc sprint

We’ve just held our fourth doc sprint. It was fun, rewarding and productive. This post is an update of one I posted a while ago, about planning a doc sprint. We’ve learned a bit since that first sprint, and I want to share those lessons with you.

Chocolate is inevitable

A doc sprint is an event that takes place over a short period of time (usually two or three days) in which people write documentation. In our case, we wrote code as well as words, because we were creating tutorials for developers. The doc sprinters may be in a room together, or collaborating online from various geographical locations.

For the August 2012 doc sprint, the Atlassian technical writers invited a number of developers and other technical communicators to join us in a three-day sprint, with the aim of producing some quality tutorials for Confluence plugin developers. (Atlassian is the company I work for. One of Atlassian’s products is Confluence wiki. Plugin developers are independent companies and individuals who build add-ons for Confluence. Some of those add-ons are available free of cost, others are commercial.)

What did we get up to during the doc sprint?

We shut ourselves up in a room and wrote like maniacs. We also ate chocolate, composed haikus when our brains needed a break, searched the documentation for golden tickets, and bombarded HipChat with inanities.

Seen on HipChat:

If there is ambient music, but everyone is wearing earphones, does it really make any sound?

Only if a tree is listening.

To synchronise with other sprinters, we held “remote standups” via webinars and video-conferencing. Why remote standups? Because we had 15-odd sprinters in Sydney, around 10 in San Francisco, one brave soul in Amsterdam, and 7 somewhere else entirely.

Update 12 September 2012: New post about the results of the sprint on the Atlassian blog: Atlassian doc sprint delivers 30 tutorials for Confluence 4.3.

When to start planning

Kicking off in Sydney

Early. We started planning in early June, for a sprint scheduled for mid August. That gave us three months to get our ducks in a row. I think we could have done it in two months, but certainly a sprint takes a lot of thinking and planning.

In our case, we wanted to  invite people to travel from various locations to our company offices, so we needed to give them plenty of warning. We also needed to get budgetary approval from management, and decide the focus of the sprint.

Involving your team and management

One of the greatest things about a doc sprint is how enthusiastic, generous and inventive people are when given an idea to play with. 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!

The people are the best part of a doc sprint.

Setting up a wish list of documents

Each doc sprint has a purpose: to develop a specific set of documentation. That purpose arises because the technical writing team and other members of the organisation know there’s a gap in the documentation.

We started by defining the focus of this particular sprint: tutorials on how to develop plugins for a specific version of the Confluence application.

I created a page on our intranet wiki, seeded it with a basic list of tutorials that I thought we needed and asked Atlassians for input. That gave us a good if somewhat unfocused list. Next I chatted to varous stakeholders 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 wish list 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 potential 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 wish list gave everyone a focus. Come the first morning of the sprint, many people dived right in without even waiting for the kickoff meeting.

Inviting people

Lively discussions

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, how many of us know 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 on the company blog, personal email messages to known members of the developer community, and messages in forums.

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 sprinters in our first sprint 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.

Learning from your previous sprint

If you’ve held a doc sprint before, you probably learned some lessons about what worked and what didn’t. It’s a good idea to put a task into your plan that tells you to go and look at those lessons learned, and see if you can apply any of them while planning the upcoming sprint. In particular, if you held a retrospective during the previous sprint, you can now go and read all the feedback and take advantage of the suggestions made. There’s more about retrospectives later in this post.

Scheduling some teaching sessions

This is something that arose from feedback given in the retrospective during a previous sprint. Sprinters are there to learn, as well as to contribute to the tutorials. In fact, they need to learn various aspects of the tools they’ll be using in order to do the work during the sprint. Some people will already be comfortable with the documentation platform, but not know the software development tools. Others will be cool with the code, but unfamiliar with the documentation tools and structure.

During our recent sprint, we ran a few short educational sessions every day. Each session lasted just ten minutes. The technical writers ran some of them, and an engineer ran others. They covered the structure of the documentation, documentation techniques such as content re-use, templates, the source repository, and best practices for writing tutorials. These sessions were well received, and were also a useful launching point for further discussion.

Templates and guidelines

Templates are extremely useful. They get people up and running quickly (reducing the fear factor) and they give a basic framework that is standard across all the tutorials. For this sprint, we updated our existing template for plugin 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. The template is still a work in progress. For the next sprint, I’d like to split this template into three: one for beginner tutorials, one for intermediate and one for advanced.

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 means that would-be attendees can simply add themselves to the list and put their names down next to the tutorials they fancy. They can even add suggestions to the tutorial wish list. This helps people to feel involved immediately, long before the sprint starts.

We also published a schedule showing the activities day by day, for each location. At first the schedule and other information on the wiki was a bit bare. We fleshed it out as the sprint date drew closer.  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.

Online participation

Video conference with San Francisco sprinters

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.

We set up the online group, chat room and webinars for our sprint:

• A chat room on HipChat. We had sprinters in various locations around the globe, and the chat room never had a moment’s rest!
• A series of webinars (online conference meetings) hosted by GoToMeeting.
• A Google Group, so that we could sent email messages to all sprinters. Actually, we have since decided that this is not such a useful channel. It was a misleading channel: people assumed (for good reason) that if they sent an email to the group, everyone would see it – but this was not true because only half the sprinters signed up to the Google Group. Also, there were too many email messages flying around. We’ll probably skip Google Groups next time.

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. At the same time as we ran the webinars, we also set up a video conference between the Atlassian offices in Sydney and San Franciso (at the start of the Sydney day)  and then Sydney and Amsterdam  (at the end of the Sydney day). That’s called burning the VC at both ends!

A lone sprinter in Amsterdam, seen from Sydney

For the daily webinar, we followed the pattern of standups (meetings held standing up, a mainstay of agile development) except that we were all sitting down. Each sprinter said what they had done so far, what they were planning to do next, and any roadblocks they had encountered. Just as in a standup, this led to useful interactions where one sprinter mentioned a problem, and another piped up with the solution they had found.

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 (Bitbucket). We keep the documents themselves on the Atlassian developer wiki. I made sure that each sprinter had the appropriate access rights to the wiki before we started.

Catering, venue and other practicalities

There are plenty 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 food. 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 buying the chocolate, because I knew I was likely to be in a tizzy and forget to do something vital. 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 the sprinters a sense of unity, and just plain prettying up the wiki pages!

For our first doc sprint, 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 theme or a 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, we could perfect our ideas for fun stuff to do during the sprint.

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 Doc Sprint Hall of Fame.

Presentations (show and tell)

Serious stuff, preparing for the demo

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 demonstrating 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.

Retrospective

We also held a couple of retrospective sessions, to get feedback and suggestions from attendees, to hear what they thought went well and not so well, so that we can do things better next time. In Sydney and San Francisco, we met with all sprinters immediately after the presentations, to go through their feedback in detail. We used the wiki retrospective page to gather comments from all attendees scattered across the globe and collate them with the feedback we have gathered.

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 wish list, 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.

Afterwards

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 have created a Doc Sprint Hall of Fame, showing photographs taken during the sprint. We’ve also written a few blogs, on the Atlassian blog as well as here on ffeathers, mentioning the great work people have done in the four sprints we have held so far.

And… sprinters get a limited edition doc sprint T-shirt!

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 a technical writing review as soon as time allows.

More random tips

• Organise to have some experts in the room and on call, and make sure the sprinters know who they are. These experts will be technical writers and subject matter experts. In our case, we had some Confluence engineers on tap to answer questions.
• Get as many of the technical reviews done during the sprint as possible. After the sprint, people move back to their “real jobs” and it can be difficult for them to allocate time to the doc sprint aftermath.

There’s more in my book

I’ve recently published a book, called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about wikis and a whole lot more. There’s an entire chapter on doc sprints, with the following sections:

• What is a doc sprint? A description of the event and its aims.
• Some examples of doc sprints. The story of three Atlassian doc sprints and a list of sprints held by other organisations.
• Planning a doc sprint. A detailed guide to organising a doc sprint and using a wiki as the platform for the sprint.
• Fun. How to add some light relief.
• Demo and retrospective. A session where sprinters show what they have achieved and give feedback on the sprint itself.
• From an organiser’s point of view. Some tips about what it is like to organise a doc sprint.
• Aftermath. The things that need doing when the sprint is over.
• A doc sprint hall of fame. A good way of acknowledging the contributions of the sprinters.
• Unusual kinds of doc sprint. A reminder about innovation sprints, documentation blitz tests, and documentation blitzes.
• A retrospective on this chapter. Wrapping up the chapter.
• References. The websites, blog posts, and other references relevant to the content of this chapter.

The book also describes other types of special sprints that are useful for technical communicators in an agile environment especially.

In closing

Here’s a post from Swapnil Ogale, one of the external technical writers who joined us on the sprint: Experiencing the Atlassian Doc Sprint – Aug 2012.

For the brave amongst us: A big hairy task list for planning a doc sprint.

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. 🙂