Open Web Docs worklog, January 2021 edition
In January, Open Web Docs was launched publicly and we’ve seen enormous support from the community. Thanks to the many of you who supported our collective already! We’re planning to update you about our workstream activities on a monthly basis and this is our first update post. Let’s look into what we’ve been working on so far!
As outlined in our launch statement, Open Web Docs is an open collective project designed to support and maintain web platform technology documentation. We’re here to ensure the long-term health of web platform documentation on de facto standard resources like MDN Web Docs, independently of any single vendor or organization.
To reach those goals, Open Web Docs is openly governed by two committees: the OWD governance committee and the OWD steering committee.
- Our governance committee administers the financial sponsorships made via opencollective.com, and explores strategic partnerships and needs for web documentation projects.
- Our steering committee develops and implements shared public roadmaps for key documentation priorities, and facilitates community involvement and execution of those priorities.
Both committees met weekly throughout January to bootstrap the project and prepare the public launch; for transparency, all the steering committee meeting notes are available in our GitHub project.
We’ve also agreed on high-level goals for the year. These give you an overview of what we’re hoping to accomplish in 2021 using our initial funding. Key goals for this year are to contribute to MDN Web Docs and to establish Open Web Docs as a long-term function that ensures that Web platform documentation is maintained via diverse funding.
As an openly-governed project, we will be transparent about our activities. We are here to serve the web community and we hold ourselves accountable to work as an independent project.
Establishing a working relationship with MDN
After MDN’s launch on GitHub, the Open Web Docs steering committee started brainstorming how to contribute to MDN effectively going forward. Chris Mills, MDN Content Lead at Mozilla and an Open Web Docs Steering Committee member, is leading an effort to come up with a content roadmap, shared between OWD and MDN.
One outcome is already implemented: We’re holding weekly MDN editorial meetings where Technical Writers from the various organizations and the community come together to discuss MDN documentation.
Additionally, Florian Scholz — our first hire and OWD Content Lead
- has been given merge privileges on mdn/content
- reviews PRs opened by the community on a daily basis.
Contributions to MDN content
We met with Mozilla Yari engineers to discuss how to change the source format from HTML to markdown and also proposed that Mozilla adopt a public RFC (“request for comments”) process for MDN so that bigger questions like a source format change can be discussed in a transparent and structured form. Work on this is tracked in mdn/pab/issues/82.
Some MDN content structures aren’t as clear as they should be; several discussions have been started and feedback is welcome:
Some new documentation got written by Florian:
- WebGL extension EXT_texture_norm16
- WebGL extension WEBGL_multi_draw
- HTML global attribute enterkeyhint (HTMLElement.enterKeyHint)
- HTML global attribute nonce
Other notable documentation updates:
- WebGL 2 is no longer marked as experimental
- Empathy is key in documentation and calling things out as “simple” is not very inclusive. Florian removed the word “simply” from all MDN docs.
Contributions to browser-compat-data (BCD)
- MDN readers love the fact that compat tables also include Node.js compat information. However, having old version numbers in there was causing confusion. Thanks to feedback from the Node.js Release Working Group, we were able to update the data and come up with a policy for initial versions for all browsers in BCD.
- BCD itself wasn’t compatible with semver until recently. Daniel Beck and Florian sorted out semver for BCD and BCD 3.0.0 was released as a consequence.
- Florian defined a spec_url property for BCD a while ago and the W3C maintains a fork that includes specification data (thanks to the work of Mike Smith). The ongoing goal is to review the spec data and merge it back into the upstream BCD repository. In the future, we would like spec sections on MDN to be sourced from BCD.
And this concludes our look into what we’ve been up to for a start! Please let us know your feedback and if there is anything you would like to see us working on.
Our first Open Web Docs community webinar will be on 17 February at 17:00 UTC. Subscribe to our calendar to see the meeting details directly.
PS: We were also able to agree on an Open Web Docs logo (for now)! 😅 Let us know what you think about it! You can see it on our Twitter channel, @OpenWebDocs.