How to use and create doc status pages

The Mozilla Developer Network offers thousands of wiki pages documenting the open web and Mozilla technologies. As these technologies and specifications evolve every day, content can become out of date pretty fast. To examine the status of the MDN documentation, documentation status pages are used to identify gaps and issues with content on MDN.

Using documentation status pages

If you want to use the information provided by documentation status pages, this quick introduction will walk you through this special kind of MDN page.

The sectioning concept

Each of the documentation status pages is dedicated to a specific technology topic, or monitors a given set of pages on MDN. Most of the time, the status pages are tracking what's going on under an MDN page tree. For example, the CSS documentation status page monitors all pages in the directory Web/CSS/*.  Similarly, the DevTools status monitors the Tools/* page tree.

Ideally, a documentation status page tracks sections with about 50 to 500 pages. That way, the chunk of content is not too small to become unimportant and not too large to track too much work.

If a topic section is way larger than that (but still belongs to a specific topic), the section gets grouped.  As an example, the Web/API/* directory is one these large sections. As you can see on the API documentation status page, the contents have been split up into a couple of groups to become more manageable. A section group is formed using a tag that's used on all pages belonging to the group.

Go to the documentation status overview page in order to find your section of interest!

Summary table

The summary table of a documentation status page looks like this:

See also localization status of this section.

The first column gives you the number of pages tracked in this section or section group. If you would like to see all pages in the section, you can click on "Pages" in the header row of the table. This takes you to an index page which lists all pages along with their tags. This can be useful for checking correct tagging and to get an idea about what content there already is in the section.

The remaining columns are all "health" indicators of the documentation section and are explained in detail below. Please note that the percentages of these metrics are based on the page count in the first column.

Tagging work

No tags

Every page on MDN should be tagged. Every documentation status page has a "Tagging standard" section and this standard should be followed when tagging pages in the section. See also the more general MDN tagging guidelines.

Needs* tags

The different NeedsXXYY tags are Indicating what type of work on a page is needed.  A few of these are: NeedsBrowserCompat, NeedsExample, NeedsNewLayout, and NeedsContent. Feel free to work on  resolving issues disclosed by these tags, but it's also helpful to add more of these tags to pages with issues.

Reviews

Pages on MDN can be flagged as needing either technical or editorial review (or both). Please consult our how-to guides on how to perform these reviews.

Outdated pages

In order to fight against outdated content, an expire date for the pages in the section can be set. This date is variable from one documentation status page to another. If a page has not been touched in 365 days, it definitely needs a double check.

Documentation bugs

There are two kinds of bug lists populating the documentation status pages:

Dev-doc-needed bugs

Engineers are setting the "dev-doc-needed" keyword to bugs that affect developer documentation. If this bugs belongs to the section of the doc status page, it will appear here.
FIXME: Link to process explanation for ddn here.

Documentation requests

In the Developer Documentation product on Bugzilla you can file bugs against MDN documentation. The different components of this product are matching to different documentation status pages. These bugs are appearing here. Open them to see what needs doing in order to resolve the task.
FIXME: Link to process explanation for documentation requests here.

Other things to do - open to do list

Besides the (automatically collected) quality indicators we have seen above, there is also room for sharing what else is needed in the content section. For example if tutorials and guides are missing or what else should be done in the content area. That information should be available in the open and shared with people interested in writing on this MDN section.

Specification coverage concept

At the bottom of the documentation status page you can find specifications that are covered by the section. As MDN is documenting the Open Web across all Browsers, the goal is to completely document the technologies standardized in those specifications as opposed to only document what is implemented in a single Browser. Ideally, all open web specifications and standards are spread across our different open web documentation status pages and that way we are making sure to document all things open web.

Topic driver box

Last but not least, the documentation status page ends with a box containing contact details. If a topic driver or curator is available for this section, you will find a contact person there, too.

Creating documentation status pages

If you would like to create a documentation status page for a new MDN section, the following will help to set up the curating concepts we learned above.

Sectioning and grouping

First thing to think about is the page tree you are going to monitor. Reminder: The rule of thumb for a section page tree is that it should consist of about 50 to 500 pages. If you are going to have way more pages than that, you might want to think about splitting your content into different page trees if your content structure allows it. If not, you could think about group tags which will help you to split your content into specific groups to monitor separately.

Getting started

Once you have an idea about the section you want to monitor, you can add a documentation status page under /docs/MDN/Doc_Status/xxyyzzz. An easy way to kick start your new documentation status page, is to just copy one of the existing ones. Edit the the JavaScript documentation status page and copy over the contents to your new one.

Using the {{DocStatus}} macro

The main macro documentation status pages are using, is the DocStatus macro. You can have a look at the macro source, the parameters are documented there as well, but we will walk through them here as well. The first three parameters are:

1. the section. Replace 'Web/JavaScript' with your section tree. This is the root page of your content section;
2. group tags. If your section contains group tags and the documentation status page should be limited to only show status for pages matching to some tags, you can specify them here. By default this array is empty '[]' but can be filled like this: '["CSSOM", "CSSOM View"]';
3. an expire date. All pages not edited after this date will appear as out-dated pages. By default all pages older than 365 days will appear as outdated as well.

Bugzilla querying

The fourth and fifth parameters are more complex as they are queries to the Bugzilla bug database. In particular, the Bugzilla Bug.search JSONRPC gets called with the specified parameters.

The base URL you can use for testing this endpoint is:

https://bugzilla.mozilla.org/jsonrpc.cgi?method=Bug.search&params=

In the case of the JavaScript documentation status page and the documentation request query used there, the full test URL is:

https://bugzilla.mozilla.org/jsonrpc.cgi?method=Bug.search&params=[{"product":["Developer Documentation"],"component":["JavaScript"],"resolution":["---"],"include_fields":["id","summary"]}]

For performance reasons, the "include_fields" parameter only contains the bug id and the bug summary, as we are not interested in more complex data of these bugs here.

You can play with the output of that API endpoint until you have the results you want. At the end you can just copy the parameter object (everything after &params=) to the DocStatus macro parameters four and/or five for dev-doc-needed query and documentation request query.

Adding custom status metric objects

The last parameter of the DocStatus macro is used to append a custom metric object. This will add a new column to the summary table and is used to track specific project's status progress or health indicators that are unique to this specific documentation status page. In case of JavaScript this object looks like this:

'{ "cleanup": {"title": "To be cleaned up", "link": "#Cleanup_project", "counter": 141 }}'

This is an object with one or more properties (here only one - "cleanup"). Each metric object consists then of the properties "title", "link" and "counter", which are all used in the summary table. See also the CSS documentation status page, where a "missing pages" custom metric object is appended.

Notes

Tags for documentation status pages

Please also tag the documentation status page itself. As it is an MDN meta documentation page, the tag "MDN" is appropriate, but also "Documentation status" should be added. Thanks!

Documentation status for zones

Sometimes getting the $children JSON (which is needed for getting the page tree) can fail silently for zones. For Example, /docs/Addon-ons$children returns null, because the actual tree lives at /docs/Mozilla/Add-ons. That case please use the actual tree URL for the first parameter of the {{DocStatus}} macro.

Additional things to do

Add your documentation status page to the overview

Please go to the overview page and add your documentation status page by using the {{page}} macro to include the summary table and a headline that links to the documentation status page you just created.

Create an index page for the section

As you may have noticed, the first column of the summary table shows a red "Pages" link in the heading row pointing to an "Index" page of your content section. Click on the link to create the page and insert the {{index}} macro with the syntax:

{{Index("/en-US/docs/<your_tree>")}}

For example:

{{Index("/en-US/docs/Web/JavaScript")}}

Localization status pages

If you would like to add localization status pages for your content section, please create translations of your documentation status page. You can do that in the language menu of your documentation status page. Choose the language of your choice and use the following syntax to set up the localization status page:

{{DocStatusQuickLinks}} {{LocalizationStatusInSection("/en-US/docs/<your_tree>", "<locale>")}}

For example:

{{DocStatusQuickLinks}} {{LocalizationStatusInSection("/en-US/docs/Web/JavaScript", "de")}}

Documentation status API

As the documentation and localization status pages are offering metrics about our content, this data is exposed in a JSON format using the following end points:

Note that this is using the Kuma API and is served as text/html and not as application/json.

Documentation status JSON

https://developer.mozilla.org/en-US/docs/MDN/Doc_status/JavaScript?raw&macros&section=json

Where "JavaScript" is the documentation status page you want to get the data for. The response should look similar to this:

{ 
  "pages": { 
    "title":"Pages",
    "link":"/en-US/docs/Web/JavaScript/Index",
    "counter":491
  },
  "noTags": { 
    "title":"No tags",
    "link":"#No_tags",
    "counter":0
  },
  "needsTags": { 
    "title":"Needs* tags",
    "link":"#Need_tags",
    "counter":45
  },

  [...]

}

Localization status JSON

https://developer.mozilla.org/de/docs/MDN/Doc_status/JavaScript?raw&macros&section=json

Where "JavaScript" is the documentation status section and "de" is the locale. The response should look like this:

{
  "pages": {
    "title":"Number of English pages",
    "counter":491
  },
  "translations": {
    "title":"Translations available",
    "counter":38
  },
  "updateNeeded": {
    "title":"Translations up to date",
    "counter":6 
  }
}