Open Web Docs worklog, end of 2021 edition
Published on January 11, 2022 by Florian Scholz

Happy New Year and welcome to the tenth 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 accomplished in November and December 2021.

In the last quarter of 2021 the team has again worked on projects the Open Web Docs Steering Committee considered the most important. See our Q4 planning issue.

Events documentation

Understanding and representing the support of events is complicated. We’ve made progress to understand what we would like to communicate to BCD consumers and agreed on a new DOM events data guideline.

On the MDN Web Docs side, this means that we will combine the current event pages and the “on” event handler pages into a single event page which will cover the event as a whole. 

The discussion of what the new unified event pages should look like is still open and your feedback is welcome. We will probably close this in January. For an example, see the XRSession docs which we’ve used as a playground. 

The new event pages will also display an inheritance diagram which you may know from interface pages. We’ve rewritten the code that produces it and once it lands it should display more cleanly on MDN reference pages.

Modernize the JavaScript Learning area

MDN’s Learning Area aims to teach complete beginners everything they need to start creating web sites. The JavaScript section of the Learn area was written in 2016 and hasn’t been fully updated to include and recommend modern JS features.

So in https://github.com/mdn/content/issues/10337 we’re taking care of this. This work includes things like: consistently using const and let appropriately, teaching newer Array features like map() and filter(), and making deeper changes like updating the module on objects to give more space to the class syntax.

The Learning Area is an important part of MDN, and we think it’s especially important to help more people become web developers. We hope this work will help people take advantage of the many improvements that have been made to JavaScript over the last few years.

We’re expecting to wrap up this project in January 2022.

Addition of ARIA states and properties

MDN’s accessibility documentation became much more complete with the addition of all ARIA states and properties. Accessible Rich Internet Applications (ARIA) is a set of attributes that define ways to make web applications, especially those developed with JavaScript, more accessible to assistive technology users.

Every aria-* attribute has been documented, with a description, values, examples, and links to the WAI-ARIA specification. Each attribute includes a list of associated ARIA roles, when they are required or forbidden, and notes about best practices.

Work is being completed to link the ARIA roles to associated ARIA states and properties, and adding links and redirects from MDN web resources to the new documentation.

Special thanks to Eric Bailey who reviewed all the ARIA pull requests.

PR reviews

In November and December, the Open Web Docs team reviewed 508 pull requests to repositories in the MDN organization.

In the year 2022...

In January, we are getting back together to plan for the first quarter and for what we’d like to achieve in 2022! You can expect us to work more on MDN Web Docs and continue to document the latest web technologies.

Thanks!

This was the first full year of operation for Open Web Docs. In this time we’ve hired three more writers, to give us a total of four staff, and delivered some major projects on MDN, including: converting all of the MDN source from HTML into Markdown, making our specification data machine-readable so it can be more accurate and consistent, and revising the WebXR reference documentation. More about our achievements can be found in the OWD 2021 Impact and Transparency Report.

We wouldn't have been able to do any of this without the financial support of our backers, and we’re very grateful to all of them. Support isn’t just financial: we’ve also benefited greatly from the knowledge and engagement of a number of expert collaborators from various organizations, especially Mike Smith from the W3C and Eric Meyer from Igalia, and Daniel Beck, Ruth John, Schalk Neethling, and Hamish Willee from Mozilla.

We’d also like to thank the volunteers who have contributed to mdn/content by reviewing PRs, writing docs, fixing bugs, and generally making it an interesting and engaging place to work. Thanks especially to Masahiro Fujimoto, himanshugarg, Anil Seervi, Himanshu, for all your thoughtful contributions, to Eric Bailey for all your reviews, and Romulo Cintra for your work documenting the Intl API. And as always Julien for continuing to lead the way for all the volunteers working on translating MDN content.

At the heart of Open Web Docs, there are the Steering Committee and the Governing Committee. We are thankful to all participants in these boards and the work they do to make OWD work! Outstanding is Jory Burson, who entirely voluntarily takes good care of us and without whom most of this wouldn’t exist.  

And this concludes our 2021 worklog updates! Happy New Year and until next month, when we return to update you about our January and New Year activities. You can reach us at @OpenWebDocs and https://openwebdocs.org.
❤️  1