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.
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:
- A presentation on doc sprints, with plenty of detail about the history and pedigree of doc sprints
and how to plan and run one.
- A blog post about learnings from a doc sprint.
- A blog post about doc fixits. A fixit is a doc sprint that focuses on fixing bugs.
Emoji tree trunk
Not related to doc sprints specifically, except that I hope your doc sprint will feature many smiling faces!
Posted on 3 March 2019, in technical writing and tagged doc fixit, doc sprint, documentation, technical communication, technical documentation, technical writing. Bookmark the permalink. Leave a comment.