May 242012
 

Here’s a helpful, handy tip for you if you occasionally edit documentation on the Mozilla Developer Network site!

Don’t delete obsolete content. If it was ever accurate, it’s probably still accurate for users of older versions of Firefox or other browsers. Instead, mark the content as obsolete.

First, you can tag individual items in a list as obsolete by inserting {{obsolete_inline(version)}}. For example:

  • Some interesting fact or link
  • Something that’s no longer true but used to be {{obsolete_inline(“gecko14.0″)}}
  • Another interesting fact or link

This indicates that the second item became obsolete effective in Gecko 14.0. You can also use “js<version>”, “css<version>”, or “html<version>”, to use versions of those specifications.

Similarly, you can mark an entire article as having become obsolete with a given version by using {{obsolete_header(version)}}.

You can also insert notes that are relevant for specific versions of Gecko by using the template {{gecko_callout_heading(geckoversion)}} in concert with the callout box div style, as follows:

  1. Put a paragraph that contains only the gecko_callout_heading template, specifying your gecko version. For example, “{{gecko_callout_heading(“15.0″)}}”.
  2. The next paragraph (or paragraphs), should be the text to appear in the callout box. This can be any kind of text, and can include notes, code snippets, and so forth.
  3. Highlight all the note text, as well as the gecko_callout_heading template line, then click the <div> icon in the toolbar. It’s on the middle row.
  4. In the popup dialog that appears, choose the style “Callout box” and click “OK”.
  5. Revel in the glory of your new callout box.

For example, if you do this:

{{gecko_callout_heading(“13.0″)}}

The foo() method became obsolete in Gecko 13.0. Instead, you should use the uberFoo() method, as follows:

var result = uberFoo(myUrl);
if (!result) {
alert("uberFoo failed! ZOMG!");
}

That will have a similar result.

The output will look like this:

This will not only let you call out plainly that something changed, but let you also show how to do things after the change was made. You should absolutely feel free to use any or all of these techniques at the same time!

The point of all this is that because we have to support developers that are still using older versions of our software, or of other browsers, we can’t simply delete content when it’s no longer useful. Instead, we have to mark it as obsolete and move on from there.

I hope this was helpful!

 Posted by at 9:50 AM

  3 Responses to “MDN pro tip: Don’t delete—obsolete!”

  1. I’ve seen this on MDN and find it very confusing. Most of the visitors will be interested in what works in the latest version. Documentation like eg. the Install Manifests is really confusing in part because all the ‘oh, in this newer version, you should/can do Y instead of X’ makes it hard to figure out what you should do in those newer versions. It’d be better if the ‘obvious’ bits were the latest, and there were (collapsed by default) blocks for ‘older versions’.

  2. (and, really, ‘new in Firefox 1.5′ is no longer useful information for anyone 1.5 was released 7 years ago…)

  3. We haven’t landed uberFoo yet, since we’re waiting on completion of uberBar and uberBaz.