Write the Docs Writing Day
Open Web Docs hosted a session at the Writing Day during the Portland 2022 edition of the Write the Docs conference. In this post we'll talk about what we worked on and how it went.
Write the Docs is a conference for people involved with all aspects of documentation, including writers, developers, editors, information architects and so on. It happens twice a year, once in Portland and once in Prague. The Sunday before the main conference is the "Writing Day", when people come to work on open source documentation projects.
Open Web Docs loves Write the Docs, in part because it's extremely inclusive, welcoming people from all kinds of disciplines that relate to documentation. This makes it an interesting place, where everyone knows different things, and everyone can learn something. We sponsored the Portland 2022 Write the Docs and hosted a session at the Writing Day for people who wanted to contribute to MDN.
We prepared a few projects for participants. The two that resonated most with people were:
- fixing sidebars in the Web API documentation.
var to declare variables. For a long time now this is considered bad practice, and it's recommended that people should use
In preparation for the Writing Day we made a list of 300 pages that mentioned
var, and asked attendees to replace it with
const as appropriate.
On MDN sidebars are added to pages using macros. We made a list of all the pages under Web APIs that were missing a sidebar, and asked attendees to add the correct macro call. This amounted to about 50 pages.
On the day
From Open Web Docs, Will Bamberg, Estelle Weyl and Queen Vinyl Da.i’gyu-Kazotetsu were there to host the session, and we were joined by about 20 volunteers. We walked through the process of editing a page on MDN using the GitHub UI and explained the activities.
From then the session was very quiet, as volunteers worked hard all day filing GitHub PRs to fix the problems, and OWD staff reviewed them and answered the occasional question.
Many people stayed for the whole day and filed dozens of PRs.
At the end of it:
- we cleaned
- we added sidebars to all pages under Web APIs that were missing a sidebar, with the exception of only four, which all need more complex fixes.
Especially the removal of
var is a substantial improvement to MDN Web Docs. Our own documentation advises against the use of
What we learned
We learned, first, what we already knew, that Write the Docs attendees are welcoming, engaging, generous, and generally a pleasure to work with.
Many attendees did not have previous experience of working with GitHub, the PR model, or docs under source control. It was helpful to have an introductory session about this. As it turned out, the technical side went smoothly. People quickly understood how to use the tools and were able to be very productive. It might have been worth spending more time up front exploring other tools, which would enable people to submit fewer, larger PRs: a limitation of the GitHub UI is that each PR can only include one file. In general it's worth organizers explicitly considering what they are giving back to attendees in terms of learning how to use these tools.
Successful projects tend to be ones that are well-defined and fine-grained, meaning that even a small contribution can be complete and useful. Next time we would like to prepare some projects which allow volunteers to engage more deeply with the content, but it's challenging to do that while still keeping projects accessible.
We've felt quite inspired by the progress our volunteers made towards cleaning
var from our documentation, and have filed a tracking issue to finish removing
We'd also like to consider how we could help writers who are new to Git and GitHub learn how to work with these tools.
Finally of course we'd like to thank Write the Docs, for enabling such a great community, and the volunteers who spent their Sunday helping to improve MDN: