Blog Archives

How to run an open source doc sprint

Last week I ran the Kubeflow Doc Sprint, an event which brought open source contributors together from all corners of the world to write docs and build samples. We worked in groups and individually, chatting over video conference and on Slack, collaborating via online reviews and comments. We tackled complex technology which for some of us was entirely new. We learned a lot and achieved a lot.

Planning a large doc sprint may seem like a daunting task. Actually, it’s a large set of not-too-daunting tasks. The daunting bits are (a) knowing what the necessary tasks are, and (b) getting organised to complete the tasks. If you’re considering running a doc sprint, I hope this blog post gives you some useful pointers.

A bit about the Kubeflow Doc Sprint

doc sprint is an event where people get together to write documentation. The time frame can be anything from a few hours to a few days. From past experience, I’ve found that three days is a good period to aim for. It gives people time to contribute a fairly sizable piece of work and to enjoy the experience of the sprint.

The Kubeflow Doc Sprint ran from 10-12 July. We had contributors working in groups in Kirkland, Sunnyvale, and Chicago, as well as individuals online all over the world. We produced around 35 pull requests. A pull request is a set of changes that related to a given goal. For example, one pull request may add a new document or update related content in a number of documents.

My post on the Kubeflow blog includes a list of the tutorials and samples we built during the doc sprint. The blog post also has some pictures of the people in the sprint.

Optional extra: Learning on the sprint

We decided to run some short, targeted presentations during the doc sprint, focusing on documentation best practices and UX. I’d had feedback from previous doc sprints that three days is a long time to be heads down writing docs. People need a bit of variety, and they like learning new patterns that are at least tangentially related to their day job.

These are the mini talks from our doc sprint:

The tasks involved in planning and running a doc sprint

Here’s a brain dump of the things that need doing. But every doc sprint is different. My top hint, before diving into the details, is this: Make a list. 🙂 Add all tasks to the list, big and small, as soon as they occur to you. Start with the tasks from this blog post – pick the ones that apply to your situation. Then add your own.

I used a spreadsheet to track the tasks for this doc sprint, but any tool will do, provided you can share the list with others, set priorities, and make comments on the tasks. And of course, you must be able to mark a task as complete. Ticking off a TODO is one of the best feelings in the world. Your task list from your first sprint will be useful for planning your next sprint.

Preparations two to three months before the event

Start planning early:

  • Get budget approval, and check that your manager and team are happy with the idea of devoting time to the sprint.
  • Set the dates. Make sure the dates don’t clash with other related events or with holiday seasons. Avoid any important product release dates, if you can.
  • Book a venue. First, you’ll need to estimate the number of attendees you can expect. Be generous – it’s far better to have room to spread out than to be cramped.
  • Decide whether your budget provides for swag (T-shirts!) and prizes. If it does, organise the vendor and any designs you need.
  • Invite people to the sprint. I used a Google Form, which handily put the registrations into a spreadsheet for me.
  • Generate enthusiasm and discussion. Make sure people know you are committed to the sprint. That will give them the confidence they need to go ahead with travel arrangements and setting aside time to work on the sprint.
  • Order refreshments and meals, if your budget extends that far.
  • Arrange additional power extensions and cables, so that people can charge their laptops.
  • Start preparing a wish list of docs to write and samples to build. I started the wish list in a spreadsheet, then moved it to the project’s issue tracker to form the sprint backlog. Discuss the wish list / backlog repeatedly with your team and the wider community. Encourage them to add to the wish list.
  • Prepare and share an agenda.

Style guide, templates, and sprinter’s guide

It often surprises me that people are so interested in style guides. As a technical writer, I know the value of style guides, but I have a sneaking feeling that other people find them tiresome. Not so! In a doc sprint in particular, people appreciate the guidance. It’s also useful for reviewers to have somewhere to point contributors at, rather than needing to repeat the same style corrections in every review.

For the Kubeflow Doc Sprint, I wrote a style guide (that task had been on my radar for a while) and created some very simple templates.

People also need to know how to work during the sprint: prerequisites and setup, where the docs are, where the doc source is, how to preview their changes, and so on. Here’s an example of a sprinter’s guide.

Online communication channels

Communication during the sprint is key, particularly when your sprinters are distributed around the globe.

  • Set up a video conference call at least twice each day on each day of the sprint, where people can talk about their progress, check whether their work may overlap with someone else’s work, and ask for help on blockers. Useful video conferencing apps include Google Hangouts, Zoom, and more.
  • Have an online chat room going. We used a Slack channel dedicated to the doc sprint, in the existing Kubeflow Slack workspace.
  • Use a collaborative online tool for reviewing contributions and for tracking work done. We used GitHub’s pull requests (a pull request is a collection of changes related to a particular goal) and issue tracker. Take a look at the Kubeflow documentation pull requests and issues in our GitHub repository.
  • Encourage people to add detailed comments to their pull requests, reviews, and issues.

At the venue

It’s often easy to forget the practical things, yet for the participants these are key to feeling welcome and safe:

  • Post signs showing people where to go. Cover all the important destinations: the room where the doc sprint is happening; the bathrooms; the exit; coffee.
  • If participants have to sign in to the building or if they may have trouble finding the room, have two or more helpers who can escort your guests to the room.
  • In your opening speech, tell people the essentials: where to find the bathrooms; whether food is catered or not; who to contact if they encounter difficulties; the agenda.

Sprint demos

It’s a good idea to arrange a demo session at the end of the sprint. Give the participants the opportunity to showcase their work and to let you know whether they plan to finish off their work in the days following the sprint.

A demo session can be quite simple. Provide a doc where people can add links to their work. Devote the last two hours of the sprint to the demo session. Display each person’s work in turn, and ask the person to give a three-minute overview, something like this:

  • Introduce yourself.
  • State the goal of your doc in one sentence.
  • Give a short overview of the content.
  • Describe any problems you encountered.

It doesn’t matter if only a few people are ready to present a demo by the end of the sprint. The demo session gives a focus and a sense of excitement to the event. In particular, it lends momentum to the last day which might otherwise fizzle out. You can take a look at the sprint demos for the Kubeflow Doc Sprint.

The aftermath

Docs, or it didn’t happen! Write a report and/or a blog post describing the results your doc sprint. Tweet about it. Let people know it was a success, so that they’ll be keen to participate next time. Be sure to list the achievements of the sprinters. They’ve devoted time and effort to the sprint. For many of them, the results you publish will be useful in their performance reports.

If you promised T-shirts or other swag, remember to send them out to the participants.

#protip: Overcommunicate

Don’t assume people know something, even though you’ve already told them via email and in chat and in person… During an event, people get overwhelmed with information and noise and meeting new people and trying to understand new things.

So, tell people the most important things again and again, in multiple channels.

One of those most important things to tell people is where to find all the information they need. For our doc sprint, the source of truth was the Kubeflow Doc Sprint wiki.

Earlier posts

I’ve written a few posts about doc sprints and doc fixits over the years. Skimming through the posts shows just how different each doc sprint is!

Do you have any hints you’d like to share?

Many people have run open source doc sprints. If you have any hints or links, please feel free to add them as comments on this post.

A lightning talk on doc sprints

At the upcoming Collaborations Workshop 2019, run by the Software Sustainability Institute UK, I’ll be presenting a lightning talk on doc sprints. One slide, three minutes. Wow, that’s a short time for a big topic. 🙂 So I decided to blog about my talking points as well as presenting a shorter version of them during the lightning talk.

Here goes: These are my talking points for a lightning talk about doc sprints.

What is a doc sprint?

A doc sprint is an event where people get together to write documentation and, often, code.
The sprinters work together for a given period of time, usually two to three days, on a specific set of documentation.

Why run a doc sprint?

A well-organized doc sprint produces excellent results. The sprinters create new tutorials based on the needs you’ve identified. They fix doc bugs based on the hot lists you’ve put together. They learn about your product and your community, and with any luck they’ll continue contributing to the project after the sprint is over.

Why do people take part?

People have various reasons for taking part in a doc sprint. They enjoy sharing their skills and helping other people. They appreciate the opportunity for contact with other members of the development team and the community. They like the recognition that comes with having their contributions accepted into your documentation site. They like fixing stuff.

How do you run a doc sprint?’

If I were doing a full presentation rather than a lightning talk, this would be the largest part of the presentation. In a nutshell:

  • Prepare well in advance: start two to three months before the date of the sprint.
  • Think carefully about who to invite.
  • Prepare a list of the docs you want written and the bugs you want fixed.

Praise and prizes

It’s important to recognize the work people have done, and the time they have spent contributing to your documentation. There are a few ways you can reward people. Write a blog post listing the work done and the authors’ names. Link to their favourite social media account, so that people know who they are.

Provide people with stickers or badges showing the name of the doc sprint. Provide a T-shirt if your budget allows that. People love swag.

More tips

Here are some more hints that I won’t have time to mention in a three-minute lightning talk:

  • Pick a time when most people are less busy than usual – for example, the start of a quarter, or the start of a year, before deadlines start kicking in. Avoid conferences and other eventts that you know your target community will be involved in.
  • Invite everyone – software engineers, support engineers, product managers, technical writers, UX designers, and more. They’ll all have something to contribute to the sprint, whether it be defining the list of documents that need writing, reviewing the docs, or developing the docs.
  • Be ready to do lots of reviews during the sprint. As the tech writer, you probably won’t have time to write any docs yourself. It’s best to get as many of the reviews done during the sprint as possible. When the sprint is over, everyone moves on to other things, and getting reviews finalised becomes more difficult.
  • Prepare hot lists of the things you want fixed, or a wish list of the docs you want written. Consult stakeholders before the sprint, to refine your hot lists.
  • Create a sprint guide. Keep it short and simple. Include the date of the sprint, the time of the sprint kickoff meeting, people involved, links to hot lists, where to send reviews.
  • Provide a guide to updating the docs.
  • Share the results via reports, both during the sprint and in a sprint wrapup. If there’s no report, it didn’t happen.

Here are some detailed guides I’ve created after running a few doc sprints:

Emoji tree trunk

Not related to doc sprints specifically, except that I hope your doc sprint will feature many smiling faces!

Doc bug fixits – a doc sprint to fix issues

If you’re a tech writer on a fairly typical large documentation suite, your docs probably contain some inaccuracies caused by error, misunderstanding, missing information, or pages going out of date. If you’re lucky, like me, you may have an eager group of developers, engineers, support team members, product managers, and more, who’d love to help fix those bugs. Enter the doc bug fixit, or doc fixit for short.

Friendly Purple Ant by Schade from openclipart.org

Over recent months I’ve run a number of doc fixits. It’s been a lot of fun,  we’ve fixed some good bugs, and we’ve learned a lot. These tips may be useful to people considering running a fixit themselves.

A doc fixit is an event where technical writers work with engineers and other team members to update the documentation. It’s a type of doc sprint, but one where the aim is to apply small to medium-sized updates rather than add new features. The updates may fix errors in the docs or add missing bits.

Image attribution:
Friendly Purple Ant, by Schade,
from openclipart.org.

Why run a doc fixit?

These are some of the good things that tech writers experience from running a doc fixit:

  • Fix bugs and improve the docs.
  • Foster feelings of ownership of, pride in and responsibility for the docs amongst the engineers and other team members.
  • Share your tech writing and information architecture knowledge with others, and see how appreciative they are of your skills.
  • Educate people about the process of updating the docs, so they can do it themselves when they discover a small error in future. The process includes sending the doc to the tech writers for review and approval.
  • Meet people in the engineering and product teams.
  • Help the engineers see first hand how their code comments end up in the public-facing documentation (that is, the code comments that are formatted for Javadoc or some other doc generation tool, and thus appear in the generated reference docs).

How long should the fixit be?

A fixit can last anything from a few hours to a few days. I’ve found two days to be a good time period. It’s rare for each participant to be able to spend more than half a day on the sprint, and people are often called away unexpectedly to do their “day job”. A period of two days gives everyone a chance to help out, and ensures you get a good number of fixes done.

In particular if you’re working with teams in different time zones, the sprint should extend over at least two days so that people in far-flung offices get the best opportunity to work together on updates.

Things to consider before running a doc fixit

Some strategy never goes amiss:

  • Consider whether your doc set will benefit from a fixit. Ideally, it should have a reasonably large number of bugs, and a fair number of engineers and other team members who can participate.
  • Contact the tech leads and managers to explain the purpose of the fixit. Make sure they’re happy for members of their team to participate, and ask them to promote the fixit within their team.
  • Select the participants based on their product knowledge. If people have already shown an interest in the docs, they’re an excellent choice. Send them personal invitations.

How can you encourage people to take part in the doc fixit?

Motivate the participants:

  • Set a goal, such as the number of bugs to close.
  • Suggest that people examine the docs and raise bugs beforehand, so they can fix them in the fixit. That’s a good way for them to get to know the docs, and a good way to put themselves in line for a prize.
  • If possible, be present yourself at the location where most of the participants will be. It’s amazing and rewarding to see how engineers appreciate having a tech writer on tap. 🙂
  • Make it competitive. For example, “that other team’s fixit closed 42 bugs – let’s beat that!”
  • Provide food: pizzas, muffins, whatever your budget allows.
  • Award prizes. It’s great to have a number of categories, such as the first bug fixed, the most bugs fixed, the most complex bug fixed, and so on. The prizes can be small – it’s the thought that counts. And the fun.
  • Make sure people feel that the fixit is a well-organised event that will give them good material to add to their resumés.

Create one or more hot lists

Create “hot lists” of bugs that you want fixed. A hot list is a selection of items, in this case bug reports, with a characteristic in common. 

For example, you could create the following hot lists:

  • Quick, easy fixes.
  • Complex bugs.
  • Bugs that require specific technical knowledge.
  • And so on.

Make sure the bugs in the hot lists are suitable for a fixit. For example:

  • Ideally, the fix should be immediately relevant, and not dependent on a software release. That means people can submit the change and experience the immediate satisfaction of seeing it published during the sprint.
  • The fix should not require too much tech writer input. So, structural doc changes, for example, are not suitable for a fixit.
  • Take advantage of the fact that your subject matter experts are suddenly uniquely interested in the documentation. Choose tasks that require intimate knowledge of the product – where you’d have to consult your subject matter experts before you could make the update: corner cases, unexpected behaviour, and so on. In a fixit, it’s often your subject matter experts taking part!
  • Prioritise small bugs that you’re not finding the time to tackle. An accumulation of small bugs can be as bad as a single huge one, for negatively affecting customer experience.

Supply a fixit guide

Keep it short and simple. Just one page is enough. Include:

  • The goal of the fixit.
  • Date and time.
  • Location of the kickoff meeting.
  • Links to the hot lists.
  • A guide on how to update the docs.
  • How to send the updates for review and approval.
  • Your contact details.

Hold a fixit kickoff meeting

Put it on everyone’s calendars. Entice people with food.

Say just a few words, telling people about:

  • The goal of the fixit.
  • Prizes.
  • How to participate.
  • A link to your fixit guide.
  • How to find you and other tech writers during the sprint.
  • Go!

Run the sprint

Keep ’em at it:

  • Issue daily progress reports: tell people the total number of bugs closed so far, the top runners for each prize, any other news items.
  • Keep the food coming.
  • Review the incoming doc updates promptly.

Wrap it up nicely

Remember, you’ll probably want to run another fixit. Wrap this one up well, so that you can refer to it in future.

Write a report and share it with everyone involved. Describe:

  • Results (number of bugs closed).
  • Participants and prize winners.
  • Interesting factoids, such as something unexpected that happened, or the first product manager to fix a doc bug ever, …

Thank everyone involved, and don’t forget to hand out the prizes.

Learnings from a doc sprint

A doc sprint is an event where technical writers work with engineers and other product team members to develop or update documentation. A well planned doc sprint is productive and rewarding for the documentation and the participants. This post shares some of the things I’ve learned from recent sprints.

A doc sprint can last anything from a few hours to a few days. I’ve found two days to be a useful period when the focus is fixing bugs. That may seem a little long, but it gives the disparate members of the team time to contribute to the sprint while keeping their primary roles ticking along too. When working with a distributed team across time zones, it’s particularly useful to have a flexible period that gives everyone the opportunity to take part.

Sometimes people use the term “doc fixit” when the sprint is focused on fixing bugs rather than developing documentation for a new product. Either way, a sprint or a fixit is a time box focused on the documentation.

Why run a doc sprint?

The primary goal is to fix documentation bugs and thus improve customers’ experience of the product. Sometimes it’s hard for a small team of technical writers to find the time to fix the small things. Yet, to our customers, those small doc bugs can mean death by a thousand cuts.

By inviting the developers and support or sales engineers to update the documentation, we make immediate and direct use of the expertise of our subject matter experts. By inviting product managers and programme managers to assess the documentation requests and help prioritise them before the sprint, we’re making use of their product and customer knowledge too.

Another goal is to foster a feeling of ownership of, pride in, and responsibility for the documentation amongst the engineers. It’s likely that they already know the value of the documentation, but they may not feel empowered to suggest and make updates. The hands-on experience of a doc sprint gives them that power. The feeling of power lasts long after the sprint has ended.

A doc sprint offers an opportunity for people to meet each other. Technical writers meet engineers and other members of the product team that we may not cross paths with often.

Some things I’ve learned from running doc sprints

These are a few things that have made an impression on me from recent sprints, and some hints that I’ve picked up along the way:

  • Engineers and other members of the product team appreciate the value of the documentation, and are keen to help improve it.
  • When deciding which tasks to allocate as suitable for the doc sprint, include some gnarly ones. It’s tempting, as a technical writer, to think that some tasks can be handled only by a technical writer. Well, that is true for some tasks 🙂 but recently I’ve found it’s rewarding to err on the side of “let’s do it”. Big things happen in a doc sprint. Big bugs get squashed with surprisingly little fuss.
  • As the technical writer, be prepared to spend the entire period of the doc sprint reviewing changes, rather than making changes yourself. The main benefit of getting software engineers and support engineers to fix bugs is that you’re making direct use of their technical and business knowledge. They know the products and systems, and the ways the customers use them. On the other hand, the engineers don’t necessarily know the ins and outs of your documentation system. So, while the facts are probably right in the documentation created during the sprint, you’ll need to tweak the language and the adherence to other documentation standards like content re-use and page structure. It’s best to do that as part of the sprint, so the bugs can be closed off.
  • Create bug hot lists, to give people priority and focus. A hot list is a collection of bugs of a certain type. Since they’re fairly crucial to the success of a sprint, I’ve dedicated a separate section to hot lists below.
  • Hold a kickoff meeting at the start of the sprint, to give people information about what they’re doing and how to do it. Keep the kickoff short: 15 to 20 minutes is good. But allocate an hour, in case people have lots of questions.
  • Create a sprint guide that you can share with the sprint participants. The guide should be short and sweet, including information such as the date(s) of the sprint, the aims, the sprint organiser, the time of the kickoff meeting, the links to the bug hot lists, information on how to update the documentation, and where to send the reviews. Walk through the sprint guide at the kickoff meeting.
  • If you have the budget, provide food and prizes. For example, cakes at the kickoff, and prizes for most bugs fixed, most scary bug tackled, and so on.
  • Send out a report on how things are going at the end of the first day, as well as a wrapup after the sprint has ended. Include interesting bits of information such as who fixed the first bug, how many bugs have been fixed so far, and the scariest bug fixed.

More about hot lists

A hot list is a collection of bugs of a certain type. Many bug tracking systems offer a way of creating hot lists, naming them, and allocating bugs to them.

Hot lists are key to the success of a doc sprint where the focus is fixing bugs. When planning the sprint, I spend quite some time devising a set of hot lists that helps define the aims of the sprint, then filling the hot lists with issues. It’s worth it. When the day of the doc sprint dawns, people can get started immediately, even if I’m not there yet. (That last is particularly handy when my day starts five hours after many of the team members’ due to time zones.)

It’s fun to think up some attractive, appealing names for the hot lists. For example, being in Australia, we chose the name Mozzie (mosquito) for the hot list of small, easy fixes. For the big scary bugs, we chose Huntsman (a rather large, strangely beautiful, but admittedly scary, spider). In our most recent sprint, we created a hot list called Product Manager’s Choice (fix these bugs to win a PM’s mark of honour) and another called Technical Sales Engineer’s Choice (fix these bugs to win a TSE’s undying gratitude).

Note that a bug can appear in more than one hot list. For example, a big complex doc request could be a Huntsman as well as a Technical Sales Engineer’s Choice.

Have one master hot list for the sprint, which includes all bugs to be tackled during the sprint. This hot list will be invaluable in tallying up totals when the sprint is over. It’s also a good container for bugs that don’t fit into any of the other hot lists, but which you’d still like tackled during the sprint.

Having hot lists also makes it easier to award prizes based on the hot lists.

More about doc sprints

If you’d like to know more, try some earlier posts on planning and running a doc sprint. The sprints I’ve been involved in recently have focused on bug fixing. In earlier sprints we created entirely new documentation sets.

Bug husks

These are the husks of two cicadas that I spotted while walking in the bush. The bugs themselves have shed their skins and gone on to bigger, better things.

Cicada husks

Invitation to a webinar about doc sprints tomorrow

Along with the Society for Technical Communication (STC) I’ll be presenting a webinar tomorrow, about doc sprints. It would be great if you can join us!

The webinar is titled Doc Sprints: The Ultimate in Collaborative Document Development. It’s full of information about planning and running a doc sprint, and how doc sprints are useful in developing the documentation our readers need.

As well as information gleaned when running doc sprints at Atlassian, I’ve included stories and tips from doc sprinters around the world: Anne Gentle, Swapnil Ogale, Ellis Pratt, Katya Stepalina, Andreas Spall, Jay Meissner, and Peter Lubbers. The stories are what make a good doc sprint awesome.

How to sign up for the webinar

Dates, times, and registration details are on the STC site: Doc Sprints: The Ultimate in Collaborative Doc Development.

Invitation to a webinar about doc sprints tomorrow

Oh, just so you know, it will be 6am here in Sydney. I’ll watch the sun come up while presenting the session. 🙂

%d bloggers like this: