Open Web Docs worklog, May 2021 edition
Published on June 11, 2021 by Florian Scholz
Welcome to the fifth 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.
This month
MDN Markdown conversion
At the moment we write MDN pages directly in HTML. This is hard to write and hard to review. It's easy to make mistakes like missing closing tags or getting the nesting wrong, and it's hard for reviewers to spot these kinds of mistakes. Also, we have to escape HTML tags in any example code we write, which is difficult and error-prone. In practice, this makes writers concentrate so much on the markup that it's hard to concentrate on the writing itself.
So in Q2 we started a project to convert the authoring format into GitHub Flavored Markdown. We're starting with the JavaScript documentation, which represents about 1000 pages, or one tenth of the total number of en-US pages in MDN.
This month we've continued work on this project:
- We’ve resolved all the major issues about how we will represent MDN content in Markdown, and written up a specification for it: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN.
- Gregor Weber has been implementing this specification, as well as a converter to get us from our current HTML into our target Markdown format, and updating the Yari tooling so it works with Markdown source.
- We’ve cleaned the JavaScript docs to the point where we can start test runs of the converter, and the result is looking really promising. We’re close to the point where we can ask people to start trying it out and look for problems, and soon after that we will be able to roll it out.
- Looking to the future, we’re cleaning up other areas of the content to make them Markdown-friendly: we’ve removed almost all inline styles from the CSS pages and have started removing them from the Web API pages: https://github.com/mdn/content/issues/5438.
Specification sections
In May, we continued working on MDN’s Specification sections.
- As mentioned in the April worklog, Mike Smith and Florian finished adding relevant specifications to BCD features.
- Florian also wrote a PR that will check spec_urls in BCD against the w3c/browser-specs repository to make sure we only use relevant specifications.
- The MDN JavaScript docs and the MDN HTML docs now make use of these specification URLs from BCD.
- The other MDN doc sets now have the `browser-compat` front-matter thanks to the pull requests of Jean-Yves Perrier. In June, we can build upon this work and roll out the BCD-powered specification tables more broadly to finish up this project.
Browser compat data
We’re continuing to help with improving the browser-compat-data project.
- After previous discussions within the BCD community and browser vendors, Florian made a proposal to add preview browsers to the project. This will help with recording support data for browsers like Firefox Nightly, Chrome Canary, and Safari Technical Preview. Caniuse is already well equipped to show this information and in June Florian will work on the MDN Yari renderer to allow this to work with MDN compat tables, too. If you are a BCD consumer, you might want to check out the enhanced data structure which we plan to make available in a BCD 4.0.0 release.
PR reviews
In May we reviewed 300 pull requests to GitHub repositories in the https://github.com/mdn organization.
Next month
In June, we’re planning to:
- Finish interviewing applicants for our Tech Writer / Advocate position to welcome a new team member really soon!
- Get together for quarterly planning meetings, so we can determine documentation projects we’d like to work on in Q3.
- Finish our current projects as much as possible.
And this concludes our May update! We will be back updating you about our June activities. Please follow the @OpenWebDocs Twitter channel for updates in the meantime.
A special thank you to Chris Mills
Chris Mills announced his last day as Mozilla’s MDN Content Lead after taking good care of it for just under 8 years. We would like to use this opportunity to say thank you! Chris really made a difference to MDN and impacted millions of web developers over the years. The MDN 15th anniversary blog post highlights some of the bright projects Chris' leadership made possible within the MDN team.
All the best for your new endeavours from Jory, Will, Florian and the rest of the Open Web Docs crew!