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!

Documentation that developers need to do their jobs

A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.

That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!

The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.

Information about the project and system they’re working on

  • Who the people are: engineering team members, product managers, technical writers, stakeholders.
  • Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
  • Goals: Mission, vision, goals for the upcoming month/quarter/year.
  • Product requirements document for the system, application, or major feature that they’re working on.
  • Design documents.
  • Architectural overview, preferably in the form of a diagram.
  • Comments in the code, written by their fellow developers.

Help with their development environment

  • How to set  up the development environment for the application/system that the team is developing.
  • Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
  • A pointer to the issue tracker used by the team.
  • Guide to the team’s code review tool and procedures.
  • Best practices for writing automated tests, and information about existing code coverage.
  • Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
  • Where to go with technical and tooling problems.

Coding guides

  • Coding style guides for each programming language in use.
  • Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
  • Best practices for code readability.

Sundry useful guides

  • Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
  • A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.

Too much information can be a bad thing. 🙂 I spotted this sign on a recent trip to Arizona:

Too Much Information

Mozilla Popcorn Maker and a tour of the Confluence documentation

Mozilla’s Popcorn Maker is pretty neat. You can grab a video and augment it with clickable text boxes. You can also add other interactive widgets, such as a live Twitter stream or a fully-functioning map from Google Maps. I’ve been playing with Popcorn Maker for a couple of weeks, and I thought other people may like to have a go. So I’ve put together a video for you to mess up… hrrm… review. It’s cunningly disguised as a tour of the Atlassian Confluence documentation. But actually, it’s a bit of fun. 😉

Popcorn Maker is all online. There’s nothing to download. You give it the URL of a video from YouTube or another supported location, then drag and drop events onto the video. The Popcorn Maker editing environment adds a timeline, a bit like the one you see in a Flash editor, but driven entirely by Javascript, HTML, and CSS. You also get a library of widgets to add and configure, such as text boxes, popups, maps, Twitter streams, and so on.

Jumping right in

Are you keen to try Popcorn Maker? Try making a remix of my Popcorn Maker movie, “Popping the Confluence docs“. I’d love it if you’d add a comment on this blog post with a link to your remix!

Mozilla Popcorn Maker and a tour of the Confluence documentation

Making the video itself

I used Screencast-O-Matic to record the movie itself. It’s a great tool too. Just like Popcorn Maker, everything is online. You do need to install Java on your computer, and it’s handy to have a webcam for the audio part of the movie. Other than that, all you need is your connection to the Internet. You can use Screencast-O-Matic free of charge, if you’re happy to have a watermark at the bottom of your movie.

Once I’d made the movie, I uploaded it to YouTube and then used Popcorn Maker to annotate it and make it available for remixing.

Some thoughts on Popcorn Maker

It’s pretty cool to be able to grab a video from YouTube (or Vimeo, Soundcloud, or an HTML 5 video) and add bits to it online, all within your web browser. Nifty technology!

But I think the huge potential lies in the fact that anyone can remix the videos. Just grab a movie that someone else has created, and decorate it yourself.

This has very interesting possibilities for collaborative development of “how to” videos. Another use that springs to mind: The review of videos. Instead of writing separate notes, people can paste their comments directly onto the relevant spot in the video. And they don’t need specialised tools to do it.

The icons and styling in general could do with some tender loving care from an artist or designer.

The integration with Twitter, Flickr and Google Maps is awesome! It makes me wonder what other integrations would be useful. Perhaps a HipChat room. Or an RSS feed from WordPress?

I’d also love to see some way of finding and sharing remixes of a given video. Ha ha, searching for “Popcorn remixes” brings up a number of song remixes!


Experiences with readers’ comments on the Atlassian documentation wiki

People are what matters in the documentation world. The docs are for the people and increasingly by the people too. One way of giving people a chance to contribute to, and help each other via, the documentation is by allowing them to comment publicly on the doc pages. Susan Grodsky asked me to write something about Atlassian’s experiences with comments on our documentation wiki. Here goes.

There’s a lot to talk about: setting the permissions that determine who can add comments to the pages, managing those comments, the sort of comments people make, how many comments we receive, and above all, is it a good thing or a bad thing to allow public comments on the documentation?

I’ve done some analysis of the comments we received over a week, from 7th to 14th January 2011. This may be a fairly quiet time of year, but it happened to be the period when I had time to do the analysis.

A bit about our documentation wiki

We write and publish all our documentation on a single Confluence site:, fondly known as CAC. It hosts the documentation for all our products: JIRA, Confluence, Crowd, FishEye, Crucible, Bamboo, JIRA Studio and more.

Each product has its own documentation “space”. Most products in fact have a number of spaces, one for each major release of the product. Many products also have a separate space devoted to developer documentation – APIs, plugin frameworks and the like. If you go to the CAC dashboard and scroll down, you’ll see the list of spaces on the left-hand side of the screen.

And yes, the documentation for the Confluence product is hosted on Confluence itself. The Confluence documentation space is just one of the spaces on CAC.

Stats of visitors to the documentation wiki in a week

To give some context to the number of comments received, I looked at the traffic that the documentation site received in the week of 7th to 14th January 2011.

Across the entire wiki:

  • 99 329 people visited the site, in a total of 157 312 visits.
  • 45 549 pages were viewed a total of 540 488 times.
  • Number of comments on all spaces: 98

Confluence documentation (DOC space) only:

  • 1 793 pages were viewed a total of 99 310 times.
  • Number of unique page views: 78 037
  • Number of comments on this space: 39

My previous blog post has some pretty pictures and more information from Google Analytics.

Analysis of comments on one documentation space in a week

Here are the results of my analysis of the comments received in the week of 7th to 14th January 2011 on the Confluence documentation (DOC space) only.

  • Number of comments on the DOC space in that week: 39
  • Who made the comments:
    • 18 comments were anonymous – added by someone who was not logged in to the wiki.
    • 21 comments were from logged-in users.
  • What the comments were about:
    • Offering information, hints and tips: 9
    • Suggesting an addition/correction to the documentation: 2
    • An unhelpful comment, possibly meant to be humorous: 1
    • Requesting help on functionality (“how do I…” or “is it possible to…”): 9
    • Requesting support (when something does not work as expected): 13
    • Suggesting a feature or improvement in the product: 5

How I tracked the comments

Google Analytics does not show statistics specifically for comments. Instead, I used an RSS feed generated by Confluence to retrieve the comments over the time period I wanted. (To define the RSS feed you want from a Confluence site, click “Feed Builder” on the Confluence dashboard.)

Permissions and public signup

How do we determine who can add a comment? Confluence has a useful permissions scheme. You can grant permissions to specific users, to groups of users, and to “anonymous” users, the last being people who have not logged in.

Each space has its own set of permissions. The permissions determine what people can do with pages, with blog posts, with space administration, and of course with comments. For example, you might choose to allow only a specific group to add and update pages in a given space. That group might be the technical writers, or the company employees. In another space, you might allow everyone to add and update pages, but only a given group to delete pages, and so on.

Talking specifically about comments: For the Atlassian documentation spaces, we have set the permissions to allow everyone to add a comment. Even anonymous users can add comments. Only Atlassian staff members can remove comments.

We have also enabled public signup on the wiki. That means that anyone can sign up for a username and then log in, immediately and at any time. Once logged in, they’re not “anonymous” users any more. They need to enter an email address, but basically they can use any name, username and email address they like.

How we handle the comments

At Atlassian, each technical writer is responsible for a specific set of documentation spaces. We keep a close eye on what’s happening in the documentation, including any comments added to the pages. There are two ways we do that:

  • Select the “watch” option on the space. When you are watching a space, Confluence sends you an email notification of all updates in the space, including comments.
  • Use an RSS feed, configured to show all activity over a given period of time.

As you can see from my analysis above, many of the comments are from people asking for help rather than making suggestions about the documentation itself. The Atlassian Support team monitors the documentation spaces too. The support engineers are really great at responding to comments. We could not do it all without them.

What’s more, readers often help each other. To me, this is one of the most rewarding aspects of allowing public comments.

The technical writers jump in to answer the comments that relate to the documentation. We answer the comment, update the page if necessary and thank the person for their input. A week later we remove the comment and our reply.

Well, that’s the plan anyway 🙂

In practice, we often don’t have time to respond to all the comments appropriately. We also don’t have time to go back a while later and remove all the comments that the support team and other customers have answered.

The result is that many of our documentation pages, especially in the older spaces, have long strings of comments attached.

We’re considering writing a script that we can run regularly to delete comments that are over two years old (or whatever period we choose). The principle is that the page will have been updated a few times and most comments will be irrelevant after such a long period.

If we do start using such a script, we will write up our comments policy so that wiki users know their comments will disappear eventually, even if we haven’t explicitly replied to every comment.

Are people nasty?

We don’t often see malicious comments. There is of course the occasional frustrated person who can’t get something working. We usually ask them to raise a support request or report a bug on the issue tracker, because the documentation is not the place for venting frustration or for getting immediate help with an urgent problem.

What about spam?

Confluence has Captcha for spam prevention. We have configured it to spring into action whenever an anonymous user adds a comment. Captcha prompts the user to read some text from an image and type it into a form. This is very effective in preventing spambots.

We do get the occasional spam comment from real people – often someone trying to sell watches, funnily enough.  They add their advertisements to the pages about wiki notifications and watches. 🙂

We remove spam comments as soon as we spot them.

Some examples of comments

Here are some of the comments we have received. They’re not all from the week of 7th to 14th January 2011. Instead, I had a look around to find some interesting and representative comments all over the wiki. Most are from the DOC space, though the last one is from the CROWD space.

Some people use the comments just to try out the wiki functionality:

Experiences with readers’ comments on the Atlassian documentation wiki

Experimenting with wiki comments

Others get a bit more adventurous, and check to see if they can code JavaScript into a comment:

Experiences with readers’ comments on the Atlassian documentation wiki

Trying out a bit of JavaScript

People share macros they have written to extend the wiki functionality. This comment was on a page about the {include} macro. Someone has written a related macro:

Experiences with readers’ comments on the Atlassian documentation wiki

Sharing a macro

People do tell us off when something goes wrong. This comment was on the page about backing up and restoring a Confluence site:

Experiences with readers’ comments on the Atlassian documentation wiki

Telling us off when something goes wrong

Other people jump to our defence. Below is a continuation of the comment above, and a reply from someone else. The reply is the comment that I counted as “unhelpful, possibly meant to be humorous” in my analysis above:

Experiences with readers’ comments on the Atlassian documentation wiki

Jumping to our defence

I stepped in to smooth the troubled waters:

Experiences with readers’ comments on the Atlassian documentation wiki

Smoothing troubled waters

Here’s a helpful comment about the documentation itself. Someone who shall remain nameless 😉 had forgotten that we’re not in 2010 any more. This comment was on the release notes:

Experiences with readers’ comments on the Atlassian documentation wiki

Pointing out a typo in the docs

Next is possibly my favourite string of comments, because it’s so cute and funny and totally off topic. The comments are still on the page:

Experiences with readers’ comments on the Atlassian documentation wiki

Been there, done that, got the T-shirt

Readers help each other. To me, that’s the most beneficial aspect of allowing public comments:

Experiences with readers’ comments on the Atlassian documentation wiki

Helping each other

A good or a bad thing?

Receiving and responding to comments keeps the documentation alive, dynamic, iterative, constantly improving. The best of agile.

It’s also chaotic, time consuming and open to occasional abuse.

From looking at the comments themselves, I’d say our customers appreciate being able to have their say, ask questions and help each other.

Me? I love it. I would find it hard to go back to a form of technical writing where there’s less contact with the readers. But I do wish I had more time to give due attention to the comments we receive.

Thank you to everyone who comments on and contributes to the wiki documentation. You are stars!

%d bloggers like this: