Open Web Docs 2022 Q3 report

2022-10-27 - Open Web Docs staff - RSS feed

In 2022 Q3, OWD:

  • was the major contributor to the mdn/content repository:
    • made 1,945 reviews for PRs merged into mdn/content, 63% of all reviews.
    • made 284.5 of the PRs made to mdn/content, 11% of the total and twice as many as any other contributor.
  • led projects to:
    • update thousands of JS code samples in MDN to use modern practices.
    • integrate markdownlint into the mdn/content repository.
    • ensure MDN content and examples follow best practices.
  • launched a website at https://openwebdocs.org and Carle, the book worm, the new OWD logo.

This report provides an update on Open Web Docs for Q3 2022. It’s split into the following parts:

  1. Goals: a restatement of the overall goals of the organization.
  2. Impact: a summary of day to day contributions to documentation projects.
  3. Projects: a summary of completed projects.

Goals

Just like in 2021, the main focus of Open Web Docs in 2022 has been contributing to MDN Web Docs.

This takes the form of contributions to the main content repositories under the https://github.com/mdn GitHub organization:

Impact

The value of MDN

MDN is an essential resource for web developers. It:

It is therefore essential for the web developer community that MDN continues to be maintained and improved, and the core team continues to be supported in reviewing PRs from the contributor community.

The contributions of Open Web Docs

Open Web Docs is the most significant organization contributing to MDN content maintenance. Of the multiple MDN organization repositories supported by Open Web Docs, the busiest is mdn/content, which contains the source for MDN’s pages. This repository is extremely active:

This report will demonstrate OWD’s contribution to the day-to-day maintenance of mdn/content with two metrics:

Both these metrics contain contributions by OWD team members, other organizations that help maintain the repository, and volunteer contributors. Contribution metrics are divided into the following groups:

As @queengooborg works for both OWD and Mozilla, her contributions have been evenly split between each organization.

PRs merged to mdn/content

All merged PRs: 2607
OWD: 284.5
W3C: 42
Mozilla: 136.5
Other: 2144
Percentage pie chart. OWD: 10.9%, Mozilla: 5.2%, W3C: 1.6%, Other: 82.2%

This demonstrates how, of organizations contributing to mdn/content as measured by PR volume, OWD is the biggest contributor. It also shows that mdn/content gets a huge volume of contributions from volunteers: 82.2% of PRs in Q2 were “Other”, which is mostly volunteers.

Reviews of mdn/content PRs

All merged PRs: 3090
OWD: 1942
W3C: 349
Mozilla: 193
Other: 603
Percentage pie chart. OWD: 62.9%, W3C: 11.3%, Mozilla: 6.2%, Other: 19.5%

The small OWD team provides the largest number of PR reviews to mdn/content, by a significant margin. OWD technical writers performed 63% of all reviews on merged PRs in the quarter.

Projects

In the third quarter of 2022, OWD completed the projects listed below.

Modernization code samples on MDN

During the 2010s, JavaScript evolved substantially as a language. The MDN Web Docs JavaScript documentation dates back to ES3. The docs were completely revamped around 2015 (for ES6); however, since then, the docs didn’t see a major update throughout. New features were documented and used latest best practices, but docs for older features mostly demonstrated best practices of the time.

MDN Web API code samples were in a similar situation. They were partly updated for ES5 and ES6, however they weren't modernized consistently on all pages, which often lead to a perception of old school and inaccurate code snippets.

MDN Web Docs' primary audience is web developers. We want to have examples that can be used in most professional projects. Not using ES6+ features in 2022 is problematic as:

In Q3 2022, we agreed which modern JS features to use on MDN, then applied them to most of our static examples.

We proceeded in three phases.

  1. First, we drove an open discussion to define JS features that are in common use now. The discussion was vivid and civil and was noticed in the JS community. The newsletter “JS Weekly” had a mention about it in one of its episodes, and 19 people participated in the discussion with a total of 81 messages; much more than usual MDN discussions. In that discussion, a consensus was reached about which JS features to use. Examples are, among other things:

    • using for…of or .forEach instead of classic for(;;) structure,
    • let and const instead of var
    • template literals,
    • arrow functions

  2. In the second phase, we applied the consensus to most static examples on MDN. We created a community of contributors to help us. With the help of more than 20 contributors and more than 200 PRs, we updated most of the 16332 static examples on 6396 pages on MDN. We limited ourselves to the most common features. This was enough to change how MDN examples are perceived: from old-style coding examples, they are now modern-style examples.

  3. Finally, the third phase consisted of updating MDN's JS coding guidelines. We also worked by consensus between all maintainers of MDN and created a single PR with 298 comments. This allowed us to communicate the new style to most maintainers but also to be able to refer to agreed conventions when divergences occur.

MDN is so large that there is still a lot to do after this project. For now, we focused on static examples on MDN pages. MDN also has interactive examples and a corpus of external examples (js-examples, css-examples, dom-examples, …); these examples should also be updated to the new guidelines. We hope to do this in the future. Still, as this is a significant piece of work, we would like to group this with a few other modernization activities that are needed: we would like to lint these examples with ESlint (to detect errors), avoid outdated APIs (like using the Fetch API instead of XHR), as well as fix any accessibility and semantic issues. We think it is a good idea to triage these structural issues, drive discussions about best practices and then apply the changes to all MDN pages.

To sum up, we renovated all static examples on MDN. They now use modern JS and can be more easily copied and pasted into real projects. They also teach better practices to developers. Working with the community on this project has been gratifying, and it helped us finish the whole project in a quarter when otherwise these mass-changes on thousands of MDN pages can take much longer.

Linting Markdown

The migration of MDN pages to Markdown improved the quality of MDN pages and its maintainability. In comparison to HTML, Markdown is easier to read on GitHub and leads to simpler diffs when reviewing PRs. It is also a lot more concise, resulting in more homogeneity of the source of MDN documents.

This homogeneity allows us to use linters to enforce a better structural and typographic coherence.

In Q3 2022, we worked with the community to integrate the most common Markdown linter, markdownlint, into the writing workflow. We were particularly cautious, as it is the first linter we added to the writing process. Tooling should help writers and first time contributors, not annoy them.

To simplify editing for writers, we want Markdownlint to autocorrect all what can be auto-corrected. That way, writers don't need to know all the details of using Markdown (like empty lines before lists) or of our writing guidelines (like using underscore for italics, and two stars for bold)

The challenge resides in integrating the linting with the two workflows:

When editing locally, most editors (like VSCode) warn writers when they make an error. When using the online GitHub UI, there is unfortunately no indication when a contributor doesn't follow the markdownlint rules.

Our challenge was to find a solution for both ways.

To solve this, we needed three pieces:

  1. A markdownlint bot, running daily, which fixes markdownlint errors automatically, or notifies about non-auto-fixable errors.
  2. A test in the GitHub CI, flagging the errors in the PR, allowing writers to fix them manually if they want.
  3. markdownlint integration with Husky so each time a commit is created locally, auto-fixable errors can be fixed without contributors having to do anything.

We have a few future improvements to perform still: we want to add more rules, like preventing images without alt texts. In order to do so, we need to fix all the existing problems to make sure the current HEAD passes with zero errors, and then update our config files to enable the test.

Overall, markdownlint integration went smoothly, to the point where the daily markdownlint bot has very errors to catch. This improves the quality of the source of the docs, and we will be able to add more rules in the future.

Best practices: emulate what we teach

As noted in the value of MDN, MDN is an essential resource for web developers, second only to stack overflow, and the second most important resource for stack overflow. A large percentage of Stack Overflow answers are code snippets copied directly from MDN. MDN is itself a learning resource for new and senior developers alike. For these reasons, and more, it’s important that all examples demonstrate accessible semantic best practices.

To this end, several objectives to reach this best practices goal, including (but not limited to).

Work is ongoing to ensure <input> examples that contain more than just the type attribute include recommended attributes, such as name and value on checkboxes, radio buttons, and hidden inputs and ensure examples that contain form controls have a label associated with the form control.

At the beginning of the quarter, there were 404 empty alt attributes in markdown code, and over 100 images with either the name of the image as the alt attribute value or missing alt attributes in an HTML <img> code block. Open Web Docs crowd sourced fixing over 500 alt attributes. At the end of the quarter, there are less than 125 left.

While working on the best practices goal, a lot of outdated content was discovered and updated. Many instances for “when supported” and “new to the browser” language were deleted, and the surrounding content updated to remove any ‘experimental’ feel of well supported features.