Welcome to the second edition of the OWD worklog! This series reports on our workstream activities. In case you missed it, please also see our first worklog post for January 2021 which introduces the Open Web Docs project some more.

A short but eventful month is behind us! We like to start by thanking again our generous backers on Open Collective. The continued support from the community makes us feel very proud about this initiative.

In February, we welcomed 15 new individual backers and we’re very happy about a $25,000 donation from Canva.com. Thank you so much!

Will Bamberg joins OWD staff

On February 16, Open Web Docs welcomed Will Bamberg to the team as our second full-time Sr. Technical Writer!

Will previously worked on MDN at Mozilla, where among other things he wrote and maintained docs for the Firefox Devtools and the Firefox WebExtensions APIs, and led the project to add interactive examples to MDN's reference docs. Will joins OWD from Element, where he's been working on a new website for the Matrix Specification.

Since starting at Open Web Docs Will has been reviewing lots of PRs to the mdn/content repo, and refining some plans for possible OWD projects in 2021.

Listen in on our Webinar and the JS Party Podcast

We hosted our first Open Web Docs community webinar! Thanks to everyone who participated and asked questions! You can watch the recording on YouTube.

Additionally, Florian and Will were guests on the JS Party Podcast. Episode 165 will be published soon. Listen in for a deep dive on some of the things we are up to.

Contributions to MDN content

Throughout February, we continued to meet with Chris Mills, MDN Content Lead at Mozilla and an Open Web Docs Steering Committee member, to further discuss a shared content roadmap between MDN and OWD. In the first opportunity assessment meeting, the OWD prioritization criteria has been used to assess potential projects. There are many ideas on what to work on and we’re working on completing our processes to come to a shared roadmap plan so that we can direct our forces effectively. We had a go at two ideas already:

Improving syntax boxes

An old but gold proposal to improve the syntax boxes to make them more beginner friendly has been discussed and we made a call that BNF syntaxes lead to more confusion than it helps. So, instead of this:

Syntax boxes that use square brackets or other non-obvious notations will be simplified and shown as multiple lines, like this:

An interesting follow-up idea by Hamish Willee is to also add return types to these syntax boxes. Maybe that could be another iteration? Feedback welcome! Let us know in the MDN issue.

Mixins

A change that concerns both MDN and browser-compat-data, is the way mixins are handled. What are mixins? Interface mixins in Web IDL are used in specifications to define Web APIs. For web developers, they aren't observable directly; they act as helpers to avoid repeating API definitions. 

When MDN was still a wiki, there was no pre-moderation and changes to the content weren’t discussed as much as they are now that MDN is GitHub. Additionally, many guidelines, about how to document the Web exactly, are missing or weren’t enforced. Sometimes authors documented mixins directly from the specification without talking about what they mean. So you might have seen pages like “HTMLHyperlinkElementUtils” or “NonDocumentTypeChildNode” and you wondered why you can’t call or do anything with these things. Also, what even is a non-document type child node and why do I need to care?

In February, we were able to agree on new guidelines for how to deal with this type of documentation.

• New documentation guideline for mixins
• New BCD data structure for mixins

An important take away here is that docs aren’t just cheap or outdated copies of specifications; they do more than that! MDN Web Docs speak to web developers as their main audience as opposed to browser engineers or specification authors and so sometimes this means to do some interpretation and/or rearranging of information from specifications to make things more accessible. It might even mean to hide some ugly parts that no one usually needs to worry about :)

Future work

We spent some time outlining projects that might make it into the 2021 roadmap:

Interactive examples for Web APIs

In 2017-2018 MDN added interactive “CodePen-style” examples to the JS, CSS, and HTML reference documentation. We’d love to do the same for the Web API documentation, or at least a substantial subset of it. This project would include:

• Figuring out what kind of widget we’d need to host the examples
• Designing and implementing a mechanism for integrating examples into MDN pages
• Writing lots of examples!

It’s not clear that the time is quite right for this project, but it’s one we still want to do when everything aligns.

Migrating MDN content to Markdown

Currently in MDN, content is authored directly as HTML. We’d like to investigate moving to Markdown as an authoring format, because Markdown is much easier to write and review. There are some obstacles to overcome here, though:

• Selecting a Markdown flavor that’s well-supported and has clearly defined behavior.
• Dealing with HTML elements that aren’t supported directly in whichever Markdown flavor we choose (for example, <dl> is not supported in GitHub Flavored Markdown).
• Dealing with MDN macros that might rely on <div> elements that have particular ID attributes (MDN’s live sample system currently does this).
• Dealing with any custom class attributes for things like node boxes.
• ...probably more problems that we haven’t thought of yet.

We have lots of ideas brewing how to improve Web platform documentation. In March, we are going to write up more of these ideas and prioritize them accordingly. Let us know what you think and what you would like to see us working on the most! We will be back reporting here next month. Follow us on our Twitter for more in the meantime.