Open Web Docs worklog, June-July 2021 edition
Published on August 5, 2021 by Florian Scholz
Welcome to the sixth edition of the OWD worklog! This series reports on our workstream activities and contributions we’re making to open web documentation projects, like MDN Web Docs. In this edition, you can find a summary of what we’ve been up to in the months June and July 2021.
Charter update
We’ve updated the Open Web Docs charter to clarify our focus on free content. We’re here to make web documentation available to as many people as possible and thus our work should be available for free.
Jean-Yves Perrier joined the team
We are very excited to have Jean-Yves join our team as a full-time Sr. Technical Writer.
Please welcome him and read more in the announcement post!
JetBrains joined Open Web Docs
In July, JetBrains joined our Steering committee and also kindly contributed $20,000 to our collective which got us closer to our yearly goal to fully fund four Technical Writers.
MDN Web Docs in Markdown
Although we love HTML, it’s not an ideal format for writing and editing technical documentation. In April we started a project to convert MDN’s authoring format from HTML to Markdown. This project has involved a few components:
- Specification: figuring out exactly how we will use Markdown on MDN. We needed to choose a baseline Markdown flavor and work out exactly what to do with all the features of HTML we currently use that aren’t supported in that flavor. To resolve these questions we filed a series of issues in which the core writing team could work to reach a consensus, and recorded the resolutions in a specification.
- Tools/platform: writing a tool to convert our docs from “MDN HTML” into “MDN Markdown'', and updating MDN’s Yari platform so it could render Markdown pages. For this we had the excellent Gregor Weber, working for the MDN dev team at Mozilla.
- Content updates: making MDN’s HTML compatible with Markdown so it could be converted.
In June we finished most of the specification and platform work, and in July we were able to convert the JavaScript documentation into Markdown. This comprises about 900 pages, or a little under 10% of the total pages on MDN. The conversion was pretty smooth with only one major problem, which the MDN dev team quickly resolved.
We’re now working on the CSS documentation, which comprises about another 1000 pages, and which we expect to be converted pretty soon.
Thanks to all the people who have contributed to this project up to now! We think it will make contributing to MDN a much easier experience.
Finished the specification project
All MDN reference pages now have the links to the relevant specifications generated from data maintained in the Browser Compat Data (BCD) project. We’ve finished this project and it is now an established practice to add spec_urls to BCD and have MDN load from this data. The links to specifications are kept up-to-date and validated thanks to data from the w3c/browser-specs repository. See the project issue for additional details.
Pull request reviews
In June & July we reviewed 388 pull requests to GitHub repositories in the https://github.com/mdn organization.
Projects for 2021 3rd quarter
The Open Web Docs Steering committee meets at the end of each quarter to discuss what kinds of projects should be prioritized. We’re identifying web developer’s documentation needs and came up with a few projects, see our Q3 discussion for a list. The following projects are new and we’ve got work started:
WebXR docs
WebXR is a group of standards which are used together to support rendering 3D scenes to hardware designed for presenting virtual worlds (virtual reality, or VR), or for adding graphical imagery to the real world, (augmented reality, or AR). We’re working on completing the docs for this technology on MDN and we’re also investigating how to add compat data for XR browsers to the MDN compat tables. See the project issue for more details.
HTTP docs
Since the initial publication of HTTP docs on MDN, a lot has changed. Back then HTTP/2 was still a draft and is now an established standard. Also, HTTP/3 was still an idea and is now implemented in several browsers.
We plan to review the existing HTTP documentation, update and improve it, and add a few pages about HTTP/2 and HTTP/3 that are relevant to web development. We will also use this opportunity to convert the HTTP docs to Markdown. For more information, see the project issue.
Next month
In August, we’re planning to:
- Convert the CSS docs to Markdown
- Document more of WebXR
- Refresh the HTTP docs
- Onboard team member number 4
And this concludes our June & July update! We will be back updating you about our August activities. Please follow the @OpenWebDocs Twitter channel for updates in the meantime.
🎉 1😀 1🚀 2