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!
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.
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.
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!
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 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: