Feb 202014

Among the first steps we need to take for our “Year of Content” this year is to review our existing documentation to find where improvements need to be made. This involves going through articles on MDN and determining how “healthy” they are. If a doc is reasonably healthy, we can leave it alone. If it’s unhealthy, we need to give it some loving care to fix it up.

Today, I’d like to share with you what constitutes a healthy document. Only once we know that can we dive into more depth as to how to fix those articles that need help.

Check the content’s age

Look to see how recently the content was updated. If it’s been a long time, odds are good that it’s out of date. The degree to which it’s out of date depends, of course, on what the topic is and whether or not there’s been development work in that area recently. Content about CSS is a lot more likely to go quickly stale than material about XPCOM, for example.

Review articles in areas of the site, looking to see how long it’s been since it was last changed, and use your judgement as to whether it’s been too long.

Do the pages have quicklinks?

Quicklinks appear in the left sidebar on MDN pages to offer links to related content. We are in the process of phasing out the old “See also” block at the end of articles in favor of quicklinks. If you see pages that have a section entitled “See also”, they need to be updated. Similarly, many areas of the site have standard quicklink macros that should be used, such as HTMLRef or CSSRef. These automatically construct advanced sidebars which link to related material as well as all other HTML elements or CSS properties.

Pages with no “See also” section or quicklinks may need some added; it’s often useful to provide additional links like these. However, they’re not mandatory.

Are there any KumaScript errors?

This is a big one. Any page that presents a big red KumaScript error box at the top of the page is an immediate “drop everything and fix this” alert. If you don’t know how to fix these (or aren’t able to), visit #mdn on IRC or drop me an email.

Are there appropriate examples and images?

Developers learn best and fastest by example. Any page about a developer technology that doesn’t have good code samples—with explanations of how they work—is probably flawed. Take note of pages that are missing examples, or have overly simplistic (or excessively complicated) examples. Also, most examples should be presented using our live sample system, which allows us to demonstrate inline the results of executing a piece of code.

Similarly, if an article would benefit from screenshots or other images (or videos) to help explain a topic, and doesn’t have any, that’s a detriment to its health, too.

Are there compatibility tables?

Every page about an API or technology should have a compatibility table that indicates what browsers and platforms support it. This includes both tutorials and reference pages. If these are missing, users will have a hard time evaluating whether or not a technology is ready for prime time.

On a related note, pages that are written from the perspective of using them from a particular browser are also flawed. Much of our content is still very Firefox-specific, which isn’t appropriate. MDN’s content should be browser-agnostic, supporting our developers regardless of what platforms and browsers their users are on. We need to find and get rid of boxes and banners that say a technology was added in Firefox version X and move that information into proper compatibility tables.

Do reference pages link to specifications?

Every reference page should include a link to the specification or specifications in which that API was defined. We have a standard table format for presenting this information, as well as a set of macros that help construct them.

Are pages formatted properly?

All pages on MDN should follow our style guide. Admittedly, our style guide is a bit in flux at the moment, and not all of it is written down yet. However, that will change soon (certainly by the time we dive in deeply into this work), so it deserves mentioning here. Content that deviates from the style guide needs updating.

Important: Many older parts of MDN use custom styles, or embed CSS examples within the body of articles. This is no longer allowed, and in fact the ability to edit content like this will eventually go away, so it’s important that these pages be updated to use only our standard styles, and to move all examples into live samples.

Are pages tagged correctly?

Increasingly, we’re using macros for everything from generating landing pages and menus to search filtering to building to-do lists. This depends heavily on pages being tagged correctly. Articles that don’t follow our tagging standards need to be updated so that all of these features of the MDN Web site work correctly.

Do pages need review?

Healthy articles have been fully reviewed; they have no review requests flagged for them. New articles are automatically flagged for both editorial and technical review, and these reviews may be requested at any time after the article has been created, as well. These reviews help to ensure the documentation’s quality and clarity.

Make sure there aren’t any dead ends

Every article should have links to other pages. Articles that don’t cross-link properly to other content become dead ends in which users get lost. Be sure that terms are properly linked to relevant content elsewhere on MDN; if there aren’t appropriate links to other pages, the articles aren’t healthy.

Do pages use macros properly?

We use macros on MDN for a lot of things. It’s important that they’re used consistently and correctly. By using macros to generate content, we can create more and more consistent content more quickly. For example, when linking to API interface objects, use the DOMXRef macro instead of directly linking to the object’s documentation. This macro can adapt quickly to site changes and design changes. In addition, it automatically creates appropriate tooltips and automatically handles other tasks to improve the site’s usability.

 Posted by at 12:05 PM

This site uses Akismet to reduce spam. Learn how your comment data is processed.