Open Web Docs worklog, April 2021 edition
Published on May 10, 2021 by Florian Scholz
Welcome to the fourth edition of the OWD worklog! This series reports on our workstream activities.
Facebook joined Open Web Docs
Facebook joined Open Web Docs as a lead funder and we’re happy to welcome Joel Marcey, ecosystem lead on Facebook’s Open Source Developer Advocacy team, to our committees. As a leading user of, and contributor to, web-based technologies and browsers, Facebook understands how important quality documentation is to the education and productivity of developers.
Facebook’s sponsorship will contribute to the hiring of full-time Open Web Docs technical writing staff.
Application opened for a Technical Writer / Advocate role
On April 20, we opened applications for our 3rd position in the team. We’re going to close this round of applications very soon. Please see our job posting and apply now.
This month on MDN
Specification sections
In April we shipped a new Specification section renderer in Yari (the platform that powers MDN). Content authors can now have a front-matter like this:
--- browser-compat: javascript.builtins.Array ---
Which can then be used by the Specification and Browser compatibility sections to load the content automatically:
<h2 id="Specifications">Specifications</h2>
{{Specifications}}
<h2 id="Browser_compatibility">Browser compatibility</h2>
{{Compat}}This will display the usual compat table, and for the specifications, it will query the compat data spec_urls in addition to the w3c/browser-specs repository to display the relevant specifications. You might not notice a visual change right now as the rendering looks similar to how specification tables have been displayed before but this brings us a better authoring experience as it does not involve KumaScript macros or HTML tables anymore. Further, this will be an enormous help for our conversion to markdown (see more on that below).
Also, now that we have a component where we can control what to render throughout the entire site, we can improve the specification section and make it more rich by adding further useful information from the specifications. If you have suggestions, let us know in the issue.
This change has so far been rolled out to JavaScript docs. In May, we will add it to more documentation areas like HTML, CSS, APIs, and HTTP docs.
Beginner friendly syntax sections
As discussed in our February worklog post, we agreed on more beginner friendly syntax sections for reference documentation. In April, we rolled this out to all JavaScript pages on MDN.
- Optional parameters are now shown in their own lines and we avoid the rather cryptic BNF notation. See for example the Array slice docs.
- Methods that use a callback now show their syntax with both arrow functions and callback functions. See the Array find docs.
- Generally the syntax blocks have been made more consistent throughout the docs.
We will likely follow-up on syntax sections (like rewriting MDN API docs where necessary and investigating whether it makes sense to add types & return values). For now though, this is the first OWD project that we called done! \o/ A special shout out to the reviewers Hamish Willee and Mike Smith for this one!
Markdown conversion
This month we’ve been preparing for migrating our JavaScript documentation to Markdown. In this phase there are really four parts to this work:
- Figuring out exactly what the authoring format will be. We’ve settled on GitHub-Flavoured Markdown as a baseline, but this doesn’t directly support all the things we need to do on MDN. So we need to work out which extra things we will need and what they will look like. We’ve filed a series of issues to discuss each of these things, and are working through them, trying to ensure that all voices are represented. Once we have a consensus we can update the Markdown in MDN page, which will eventually fully describe how we will write content in a Markdown world.
- Figuring out how we will convert our current content into this target format. For this we’d like to specify what our converter should do when it encounters any of the HTML constructs that we currently use. Sometimes it will convert them into our target format, sometimes it will discard them, and sometimes it will raise an error. In the last case we then have work to do to make the content compatible with our target format. We’re currently tracking this work in the main issue for this project.
- Updating our content to make it compatible with the target format. In places where we know a converter can’t reliably convert our content into Markdown without breaking it, we have to update our content manually . For example, this month we:
- removed all inline styles from the JS docs
- removed all uses of the “summary” class to select pieces of the page
- made the way we represent notes and warnings consistent, so the converter can reliably identify and convert them.
- Writing the converter. Based on this speccing work and supported by the content preparation, we’ve been implementing a tool to convert our content to the target format, emitting warnings and errors as needed. For this we're lucky to have Gregor Weber from the Mozilla MDN development team. Gregor’s also working on tooling to help us visualise the changes, to help double-check that our converted content still looks good.
PR reviews
This month we reviewed 254 pull requests in MDN repositories.
Next month on MDN
In May, we will interview candidates for our third position and will hopefully welcome a new team member very soon!
We will also make more progress on our remaining Q2 projects:
- Converting MDN content to Markdown
- Fixing mixin docs on MDN
- Up-to-date & machine readable specification links on MDN and in BCD
And this concludes our April update! We will be back updating you about our May activities. Please follow the @OpenWebDocs Twitter channel for updates in the meantime.