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.

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.