Results of open source doc fixit at Write the Docs Australia 2019
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!
Posted on 16 November 2019, in open source, technical writing, Write the Docs and tagged doc fixit, doc sprint, documentation, technical communication, technical documentation, technical writing, Write the Docs. Bookmark the permalink. 2 Comments.