This week saw the 2019 conference of Write the Docs Australia. I was delighted to be able to take part in this event. So many good discussions, interesting talks, and lovely people!
On the Thursday afternoon of the conference, I ran an open source doc fixit. A doc fixit is an event where people get together to fix problems in a set of documentation. In the space of just two hours, a group of Write the Docs attendees contributed polish and shine to the Kubeflow documentation. Two fellow tech writers from Google assisted at the event: Alec Glassford and Riona MacNamara.
Together the fixit participants fixed 33 bugs and merged 31 pull requests (PRs). Thirty-three sets of textual and formatting improvements. That’s a really great contribution to the Kubeflow open source doc set.
The screenshot shows some of the PRs submitted on GitHub by the fixit participants. A pull request (PR) is a set of changes that a contributor is presenting for merging into the open source project:
What do the resulting docs look like? One of the pages that received tech writer love was the guide to authenticating Kubeflow to GCP:
Approximately 20-25 people took part in the fixit. A few people paired up to work together, which resulted in 15 individuals submitting pull requests (PRs). Some people submitted two or three PRs, leading to a total of 31 PRs.
The participants were a diverse group. Most were technical writers, given that the fixit was part of a Write the Docs conference. A few people had prior experience of GitHub, but most were new to open source and GitHub.
Goals and tactics
My goal for this fixit was to ensure that the participants had an enjoyable experience as well as the opportunity to learn a bit about open source processes and GitHub technology. I knew that the participants would have no knowledge of the product that the docs cover (Kubeflow).
Another important goal was to contribute meaningful improvements to the Kubeflow docs. Kubeflow is working towards a v1.0 release in January 2020. In the open source world, v1.0 is an important milestone, bringing certain guarantees of stability and polish. The v1.0 docs need to be polished too.
With the above in mind, I decided on a few tactics:
- Keep the fixes relatively simple: typos, list formatting, broken links, outdated content. I did sprinkle in a couple of more complex fixes, where people needed to trawl through other PRs or issues to gather information. Those were for the folks who were already comfortable on GitHub.
- Describe the fixes in detail, so that people didn’t inadvertently change the meaning of a sentence when polishing the syntax.
- Make sure that only one person would submit a PR for a given page. I wanted to avoid messy merge conflicts, which may be frustrating and may even be difficult to resolve in the course of a two-hour fixit. I created a spreadsheet with one row per page, listing all the fixes required on that page. The fixit participants would then put their names next to one or more rows, to claim the pages they would work on.
- Have three of us (Riona, Alec, and myself) walking around the room and assisting with the tricky bits.
- Have the three of us reviewing and approving PRs as they came in, so that the participants could see the results of their work published in the doc set as soon as possible.
- Provide a detailed guide for participants, including the basics of how to work in GitHub and how to update the Kubeflow docs. I wrote the guide, then asked Alec to test it. It was a good thing that he did test the guide, because it turns out that the GitHub experience is quite different for someone who doesn’t have contributor rights to a repository (Alec didn’t yet have them when he tested the guide) as opposed to someone who does (I’m an administrator of the GitHub repo and a member of the Kubeflow organisation).
- Direct participants to use the GitHub web interface rather than the git command line interface.
- Attempt to review and approve the PRs during the course of the fixit, so that participants could see the results of their work in the repository and on the docs website. To make this happen, I granted Alec and Riona the necessary review and approval permissions on the GitHub repository where the docs reside. We’ll remove those permissions now that the fixit is over.
What happened at the fixit
At the start of the fixit, I presented a short talk introducing the concepts of open source software and documentation, and the goals of the Kubeflow project.
Then the participants chose a page to work on, based on the spreadsheet we had prepared, and started work.
- Their first task was to create an issue in the GitHub repo where the docs reside, to track their work.
- Their second task was to find the page that needed fixing, and open the page in edit mode.
- After making the necessary updates, the participants submitted a PR for review.
Alec, Riona, and I moved around the room, answering questions and helping people do the initial signups and then submit their issues and PRs.
In between answering questions, we also reviewed the incoming PRs and approved each one when it was ready for merging into the docs repository on GitHub. The continuous merge/publish tools on the GitHub project merged the change and published the update in the docs.
Hiccups and learning
All in all, things went smoothly. I’m very happy with the results. Huge thanks to the participants and to Alec and Riona for their help both before and during the fixit.
Alec, Riona and I were pretty busy helping the participants with various signup processes, GitHub idiosyncrasies, and other tricky bits. We didn’t have much time for reviewing and approving PRs. Next time, more assistants!
A few participants were confused about the difference between an issue and a PR in the GitHub repository. This reminds me how easy it is to succumb to the curse of knowledge: the fixit guide explained why it’s a good idea to create an issue (thanks Alec for suggesting this addition!) but it didn’t go into detail about the difference between an issue and a PR. If both those things are new to you, the difference is not obvious, particularly since they look very similar on GitHub.
A number of participants commented that the initial process of starting to contribute was lengthy and a bit bumpy. People need to sign up to GitHub, sign the contributor licence agreement (CLA), open a page for editing, then follow the GitHub prompts to submit the change, then create a PR (twice, seemingly, as the UI is a little clumsy). People were delighted to know that much of the process is once-off, and their second PR went more smoothly.
On a side note: We were using the GitHub UI because it’s initially a simpler experience than the git command line. Personally, I much prefer the command line. It’s restful. When I sit down with my laptop and type
git status, it’s as if I’m saying:
Hey git, it’s been a while. I got distracted by messier things, but I know you’ve been keeping track of the important stuff for me. Let’s get going.
Feedback from participants
Fixit participants said that they appreciated the opportunity to learn about open source and to have their first experience of working in GitHub.
During the general feedback at the close of the conference, people mentioned that they were pleased some parts of the conference involved active participation, instead of listening passively to talks for the full two days.
What else happened at the conference?
Write the Docs Australia 2019 was jam-packed with talks, workshops, lightning talks, and unconferences. Take a look at the full program.
Here’s the Twitter hashtag: #wtdau2019.
Thanks so much to all the organisers and attendees. Write the Docs AU 2019 was awesome. See you at Write the Docs AU 2020!
Are you coming to the Write the Docs Australia 2019 conference on 14-15 November in Sydney? You’re invited to join us in a two-hour doc fixit on Thursday afternoon, as part of the conference.
Become a contributor to an open source project, learn a bit about how open source works, and help improve the experience of Kubeflow users. All in just two hours!
During the fixit, you’ll add a touch of tech writer shine to the Kubeflow docs. Docs are a super important part of the user experience of any product. Typos and grammatical inconsistencies can spoil that UX. Yet typos and odd syntax creep into any doc set so easily, especially when the doc set is largely written by non tech writers. You can help us set things right.
Where and when
The doc fixit is part of the Write the Docs Australia 2019 conference.
- Date and time: Thursday, 14 November, at 1pm.
- Location: Water Police Court, Sydney.
You don’t need to register separately for the doc fixit. Just register for the conference, then come along to the fixit on Thursday.
Your friendly doc fixit helpers
The doc fixit hosts are:
- Sarah Maddox (that’s me: Kubeflow tech writer at Google)
- Alec Glassford (Tech writer at Google)
- Riona MacNamara (Tech writer manager at Google)
What happens at the fixit
Here’s how the fixit will work:
- Before the fixit, I’ll create a spreadsheet with a list of doc bugs that need fixing. They’ll mostly be small things: typos, consistency in page structure, capitalisation, and so on.
- At the start of the fixit, I’ll give a very short talk introducing the product (Kubeflow) and open source.
- Then the group will look at the list of bugs and each person will choose what they want to do.
- My assistants and I will help people create GitHub IDs if necessary.
- Each person will create an issue in the GitHub issue tracker, describing the bug they’re about to fix.
- Each person will then update the relevant doc on GitHub and send a pull request (PR) for review.
- My assistants and I will help people sign the contributor licence agreement if necessary. (A bot will prompt them to do this when they send their first PR.)
- My assistants and I will review the pull requests and approve each one when it’s ready.
- The continuous merge/publish tools on the GitHub project will merge the change and publish the update in the docs.
- The contributor will see their update appear in the docs!
I’ll also prepare a guide to for fixit participants, with the basics on how to work in GitHub and how to update the Kubeflow docs. The guides, in combination with the three of us helping during the fixit, should make the fixit fun and a useful learning experience for everyone.
Here’s how you can prepare for the Kubeflow doc fixit:
- Bring a laptop with WiFi capabilities.
- If you don’t already have a GitHub account, sign up for one. If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
- Sign the Google Contributor License Agreement (CLA). If you have time to do this before the start of the sprint, that’s great. If not, you can do it during the sprint.
- It’s not mandatory to do any prework, but it will help if you know some Markdown.
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!
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.
Friendly Purple Ant, by Schade,
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.
- How to participate.
- A link to your fixit guide.
- How to find you and other tech writers during the sprint.
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.