Doc sprint at Write the Docs day Australia

Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.

Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.

At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:

Dart, led by Sarah Maddox
Kubernetes, led by Jared Bhatti
Cyrus (email), led by Nicola Nye
webpack (JavaScript module bundler), led by Chris
ReactiveUI.net, led by Geoff

What happened in the sprints

[image error]I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:

Angular setup guide
Angular template syntax
Angular architectural overview
Another pull request is in progress, to update the page on the Angular HTTP client

The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!

At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.

Things people learned

[image error]For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.

Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.

For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.

The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.

For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.

It was hard work

It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.

There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.

Swapnil: “Good, OK, I’ll leave you to it.”

Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.”