Kuma Report, June 2017

Here’s what happened in June in Kuma, the engine of MDN Web Docs:

  • Shipped the New Design to Beta Testers
  • Added KumaScript macro tests
  • Continued MDN data projects
  • Shipped tweaks and fixes

Here’s the plan for July:

  • Continue the redesign
  • Experiment with on-site interactive examples
  • Update localization of macros
  • Ship the sample database

Done in June

Shipped the new design to beta testers

This month, we revealed some long-planned changes. First, MDN is focusing on web docs, which includes changing our identity from “Mozilla Developer Network” to “MDN Web Docs”. Second, we’re shipping a new design to beta users, to reflect Mozilla’s new brand identity as well as the MDN Web Docs brand.

Stephanie Hobson did a tremendous amount of work over 26 Kuma PRs and 2 KumaScript PRs to launch a beta of the updated design on wiki pages. A lot of dead code has been removed, and non-beta users continue to get the current design. Schalk Neethling reviewed the PRs as fast as they were created, including checking the rendering in supported browsers. Our beta users have provided a lot of feedback and found some bugs, which Stephanie has been triaging, tracking, and fixing.

This work continues in July, with an update to the homepage and other pages. When we’ve completed the redesign, we’ll ship the update to all users. If you want to see it early, opt-in as a beta tester.

Added KumaScript Macro Tests

Macros used to be tested manually, in production. After moving the macros to GitHub, they were still tested manually, but in the development environment. In June, Ryan Johnson added an automated testing framework, and tests for five macros, in PR 204. This allows us to mock the Kuma APIs needed for rendering, and to test macros in different locales and situations. This will help us refine and refactor macros in the future.

Continued MDN Data Projects

The MDN data projects were very busy in June, with 48 browser-compat-data PRs and 10 data PRs merged. MDN “writers” Florian Scholz, wbamberg, and Eric Shepherd have been converting MDN browser compatibility tables to JSON data, refining the schema and writing documentation. This is already becoming a community project, with almost half of the PRs coming from contributors such as Andy McKay (1 PR). Dominik Moritz (2 PRs), Roman Dvornov (6 PRs), Ng Yik Phang (2 PRs), and Sebastian Noack (16 PRs!).

The tools and processes are updating as well, to keep up with the activity. browser-compat-data gained a linter in PR 240. mdn-browser-compat-data’s npm package was bumped to version 0.0.2, and then 0.0.3. mdn-data was released as 1.0.0. We’re loading the browser-compat-data from the NPM package in production, and hope to start loading the data NPM package soon.

We’re happy with the progress on the data projects. There’s a lot of work remaining to convert the data on MDN, and also a lot of work to automate the process so that changes are reflected in production as quickly as possible.

Shipped Tweaks and Fixes

Here’s some other highlights from the 44 merged Kuma PRs in June:

Here’s some other highlights from the 31 merged KumaScript PRs in June:

Planned for July

Continue the Redesign

Some of the styling for the article pages is shared across other pages, but there is more work to do to complete the redesign. Up next is the homepage, which will change to reflect our new focus on documenting the open web. Other pages will need further work to make the site consistent. When we and the beta testers are mostly happy, we’ll ship the design to all MDN visitors, and then remove the old design code.

Experiment with On-site Interactive Examples

We’re preparing some interactive examples, so that MDN readers can learn by adjusting the code without leaving the site. We’re still working out the details of serving these examples at production scale, so we’re limiting the July release to beta users. You can follow the work at mdn/interactive-examples.

Update Localization of Macros

Currently, KumaScript macros use in-macro localization strings and utility functions like getLocalString to localize output for three to five languages. Meanwhile, user interface strings in Kuma are translated in Pontoon into 57 languages. We’d like to use a similar workflow for strings in macros, and will get started on this process in July.

Ship the Sample Database

The Sample Database has been promised every month since October 2016, and has slipped every month. We almost had to break the tradition, but we can say again it will ship next month. PR 4248, adding the scrape_document command, shipped in June. The final code, PR 4076, is in review, and should be merged in July.