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!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 3 March 2019, in technical writing and tagged , , , , , . Bookmark the permalink. Leave a comment.

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: