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
A 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:
- How to address the reader in technical documentation.
- Passive resistance.
- A short guide to writing well.
- Kubeflow: A First Impression.
- Guiding users through a journey.
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.
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.
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.
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.
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.
Posted on 22 July 2019, in open source, technical writing and tagged doc sprint, documentation, Kubeflow, open source, technical communication, technical documentation, technical writing. Bookmark the permalink. 9 Comments.
Reblogged this on TechDocs and commented:
This is a real-life write-up about “How to run an open source doc sprint” by Sarah Maddox. Kudus!
I am an passionate writer and tech lover. I have my own tech blog as well.
I am trying to reach out you on LinkedIn since long.
Could you please connect with me. If possible could you please provide your mail id so I can write to you my concerns?
Thanks and Regards,
I received your LinkedIn invitation today and have accepted it.
I love this idea! I’d love to join in a future sprint. How can I find out about them in advance?
It’s great to know you’re keen on joining a doc sprint! We’ll publish a blog post on the Kubeflow blog and tweet from the Kubeflow account in the leadup to our next sprint.
Fantastic, thanks. I’ll check it out.
Hi Sarah- I would like to join a future doc sprint. The idea seems very interesting. How do I get to know about the doc sprints?
Pingback: Write the Docs Prague 2019 wrapup | ffeathers
Pingback: Writing internal vs external docs: what’s the difference | ffeathers