Open Collective
Open Collective
Loading
Open Web Docs
About
Contribute
Budget
Connect
Open Web Docs worklog, March 2021 edition
Published on April 8, 2021 by Will Bamberg
Welcome to the third edition of the OWD worklog! In this edition we'll talk about what we got up to in March 2021.

The Open Web Docs Steering Committee provides feedback and guidance on priority work areas for OWD and on specific OWD projects. We're thrilled to welcome two new Steering Committee members this month:

Specification URLs

The “Specifications” section on MDN reference pages is used by web developers and even browser engineers to quickly find the exact and current definition of a web platform feature.

Unfortunately, many specification sections on MDN link to outdated drafts or are just 404. Every specification section is authored manually as an HTML table. This means the tables are inconsistently presented, and any time we want to change the presentation we have to edit thousands of pages.

Michael Smith and Florian Scholz continued to collaborate to get more up-to-date specification links into browser-compat-data as a spec_url property, analogous to the already existing mdn_url reference. This has a few advantages:
  • The specification URLs become machine-readable
  • We have a mapping between MDN URL, specification URL, and compat data.
  • Maintaining specification links becomes part of the process that already exists to keep browser compat data current and relevant. 
  • In the future, BCD can add tooling/linting so that outdated specification links aren’t allowed.
  • Once MDN consumes spec data like compat data, we can control the rendering of that specification section from a central place and add functionality to it easily. This also makes sure that rendering will be made consistent across all of the MDN reference pages.
In March, Mike and Florian finished adding specification URLs for CSS and HTTP features. JavaScript features are also recorded already. Getting into the large pile of specifications that define Web APIs is the next step.

On MDN, we will work on implementing a mechanism that consumes this data from BCD, so it should become a lot easier to have current specifications displayed. We might even go further and make it a matter of just requiring to add a front-matter key which will then make sure that compat data and specifications will be displayed.

Let us know any feedback in our project issue or in the individual issues.

Updating page lifecycle events

Developers often want to be notified about different stages of a user's interaction with a page: especially, at the point the user has finished with a page. Often they use the unload or beforeunload event for this, but this is not reliable, especially on mobile.

This month we updated the docs for lifecycle events (unload, beforeunload, pagehide, and visibilitychange) to recommend better practices here.

New CSS sidebar

We’ve known for a long time that the sidebar for the CSS reference on MDN isn’t as good as we’d like. This month we’ve reimplemented it to provide better navigation across the CSS docs, to expose useful pages and tools, and to simplify the sidebar architecture (https://github.com/mdn/yari/pull/3228).

Removing more mixin pages

As introduced in our February update, we were able to agree on a new documentation guideline for mixins. We’ve started working on refactoring these docs and the project is now described formally in our repository.

Florian reworked a few page trees here:
  • The DocumentOrShadowRoot mixin is now properly documented under the Document and ShadowRoot page trees.
  • The HTMLHyperlinkElementUtils mixin is now properly documented as  HTMLAnchorElement and HTMLAreaElement.
  • NonDocumentTypeChildNode is not mentioned in the docs anymore. The members are documented properly under Element and CharacterData.
  • Work is in progress to remove the ParentNode mixin page and document members under Document, DocumentFragment and Element.

PR reviews

In March Florian and Will reviewed 173 pull requests to GitHub repositories in the https://github.com/mdn organization.

Planning Q2

We’ve spent some time this month planning Q2 projects and came up with this list of things we like to work on:
There are more ideas in our project repository. If you have more ideas on content projects you’d like us to consider, please submit an issue on our project repository or reach out to us in the comment section below! 

Next month on MDN

Next month we’ll continue to fix up mixin docs and to add machine-readable specification URLs.

We’ll also start the project to migrate MDN authoring format to Markdown. This is a joint project with the Mozilla MDN engineering team, who will be implementing tools to convert our HTML content into Markdown and adapting the Yari platform so it can render Markdown as MDN pages. Open Web Docs will be helping to figure out where we’ll have to extend GitHub-Flavored Markdown so it can support all the things MDN needs it to do, and also updating our content where necessary so it’s more Markdown-compatible. We're keeping track of the issues in a GitHub project on the mdn/content repo.

And this concludes our March update! We will be back updating you about our April activities. Please follow the @OpenWebDocs Twitter channel for updates in the meantime.