Florian Scholz
Florian Scholz

Are we documented yet?

17 Mar 2014

No, we aren’t (yet).

Every wiki and documentation site fights against a big problem: Content outdates pretty fast as the software or the technologies evolve. This is more than true for MDN.

When we switched to the rapid release model, the way we document on MDN changed as well. A process for having release notes every six weeks has been set up by Jean-Yves Perrier (teoli) and our old tools like the “DocTracker”, which gets us dev-doc-needed bugs per release, were helpful. However, writing detailed documentation for all these changes in six weeks, is no longer achievable. There are a lot of more changes in six weeks today than in six weeks two years ago.

In the old days, “yes, we are documented yet!”, meant that the dev-doc-needed bug counter was near to zero for a given release.

I thought about building new tools that could answer how are doing today. Fortunately Kuma and KumaScript are open source and hackable, so that I was able to build new tools directly into MDN.

Introducing documentation status pages

So, how can we measure if we are documented yet, today?

The MDN documentation team switched to concentrate on content topics rather than to document everything belonging to a release. Several Topic Drivers started to maintain specific parts of MDN.

If you look at a content section on MDN, you can definitely identify more “health indicators” than just the dev-doc-needed bug list. To make the state of the documentation visible, we started to build documentation status pages for sections on MDN.

Let’s take the JavaScript documentation status as an example to see what we currently measure.

JavaScript doc status summary

Quality indicators:

Open to do list

Besides the automatically created quality indication list, there is also room for sharing what else is needed in the content section. For example, for JavaScript, we need to clean up our documentation for ECMAScript 6 and some tutorials and guides are missing, too. That information should be available in the open and shared with people interested in writing on MDN. So, if you are asking what you can do for MDN, you should find answers there!

Introducing localization status pages

When localizing MDN, we are speaking of 11,000 pages. This is a huge task and not all docs are worth translating. So, with the idea of content sections, we are also looking into making smaller lists of pages in need of localization.

To keep track of the localization work, a localizer needs to know if a translation is available and whether it is up to date with the English source. So, for each documentation status page there is also a localization status page.

Here is an example that lists the translation status of the JavaScript section for Japanese: Japanese localization status for JavaScript Also have a look of the translation overview pages, e.g. all sections for Japanese.

Help us!

With these status pages for both, English documentation and the translations, a lot of work becomes visible. If you have expertise in one or more of the topic sections, please have a look and help us with documenting. If you are a localizer and would like to have a status page for your language, feel free to add one or contact us to help you.

In general you can find us on irc.mozilla.org in #mdn.
You can also reach me at fscholz@moco or Jean-Yves at jperrier@moco.

The first iteration of these tools is now finished. The different documentation status pages we have right now, are monitoring around 40% of all MDN pages. We are looking into increasing that number.

Let’s document the Open Web!

PS: Pretty graphs using the doc status API

How about a nice page like arewefastyet.com or areweslimyet.com? I have built a documentation status API. Anyone wants to collect data and make that happen? :-) For instance, a JSON for the JavaScript documentation status, can be found here.