Open Web Docs worklog, October 2021 edition
Published on November 9, 2021 by Florian Scholz
Welcome to the ninth 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 October 2021.
OWD 2021 Impact Report
The team wrote a report summarizing our impact and achievements the Open Web Docs collective was able to accomplish in its founding year. Read the OWD 2021 Impact & Transparency Report.
The impact we had was only possible thanks to the generous donations from all of our sponsors and backers for which we are very grateful as we continue our journey into the second year of Open Web Docs.
Jory and Dom led a breakout session at TPAC 2021 where they shared details. A recording of the session and meeting minutes are available. You can also download a PDF version of the report.
Talk at JetBrains JavaScript Day
Florian presented the talk Documenting the Web Platform, a presentation about Open Web Docs and documenting the web platform at JetBrains JavaScript Day 2021. The recording is available on YouTube.
Markdown
During the month of October 2021, we finally finished the project to convert the authoring format for MDN Web Docs from HTML to Markdown. This has been a major project for Open Web Docs this year.
We first had to understand all the needs we have on MDN and how we would be able to meet them with Markdown. Then we implemented the tooling required by MDN’s platform to convert documentation from HTML into Markdown and the tooling to convert the Markdown back into HTML at build. We are grateful to Mozilla for lending us @Gregoor’s time in helping with the engineering requirements.
Once the tooling was in place, it was just a matter of cleaning (or preparing) about 11,300 HTML documents so they were compatible with Markdown, then converting them, and then reviewing each one of them.
We think this project of converting all MDN content to markdown makes contributing to MDN much easier and will provide a good foundation for taking MDN forward in the years to come.
ARIA
October saw many additions to MDN’s accessibility documentation with two new sections being added: WAI-ARIA Roles and ARIA states and properties. A PR with a new index page and over 50 new ARIA roles, including document structure, landmark, live region, window and abstract roles was merged into production.
While the roles were added by category, ARIA states and properties are being added in alphabetical order. Eighteen aria-* attributes were completed and merged during October along with an overview index page for the section.
These pages document the WAI-ARIA specification and provide non-normative explanations about how each role and attribute should be used, along with HTML equivalents and best practices.
MDN core DOM reference
Documentation of the DOM on MDN is very old: part of it was adapted to an era when different browsers implemented different DOM trees. This has changed. Today the DOM is highly interoperable.
MDN core DOM reference needs to be updated to remove all of the historical problems that a web developer of 2021 doesn't need to worry about anymore.
We started to update the DOM reference. This project aims to:
- Have a complete and accurate reference of all DOM interfaces.
- Have an updated set of guides describing how the DOM works.
In October, we were able to create pull requests to update Event, CustomEvent, Node, CharacterData, Text, Comment, ProcessingInstruction, CDataSection.
PR reviews
In October, the Open Web Docs team reviewed 361 pull requests to repositories in the MDN organization.
Next month
In November, we’re planning to:
- Continue to work on updating the MDN core DOM reference.
- Start work on refactoring the MDN events docs.
- Modernize the Learning Area content to talk about newer JS features
- Continue work on documenting ARIA states and properties
And this concludes our October update! Until next month, when we return to update you about our November activities, you can reach us at @OpenWebDocs. Want to join us? Visit https://openwebdocs.org.
🎉 1👍️ 2