Nov 072011

One of our initiatives on the Mozilla Developer Network’s documentation wiki is to improve browser agnosticism. That is, to ensure that where appropriate, our open web documentation is just as useful for web developers using other browsers as it is for those using Firefox. A lot of our documentation is currently very Firefox-oriented, even when it’s not necessary.

Consider this, for example:

Example of non-agnostic docs

Here we see a big banner about how this method of the DOM Element object was introduced in Gecko 1.9.1. However, it’s actually a standard DOM method. This banner should go away, and the text should be updated wherever necessary to remove any Firefox-specific discussion.

In addition, the article should have our standard browser compatibility table at the bottom. This table provides information about which releases of all the major browsers introduced support for the feature.

I’ve updated this article now so it looks the way it’s supposed to, as an example of what it ought to look like.

Noting introduction of sub-features

Some features are fairly complex; for example, the HTML <input> element has evolved over time, with the addition of new attributes and new possible values for many of them. This is where adding additional rows to the browser compatibility table comes into play. Let’s look at a few rows from the compatibility table for <input>:

Example of longer compatibility table

Here we see multiple table rows, each for a given named feature of the element being documented. In the case of Firefox, we see that type=color isn’t implemented yet, and we used {{unimplemented_inline(547004)}} to include a link to the corresponding bug. We also have the WebKitBug template for linking to WebKit bugs, and should add an unimplemented_webkit_inline or similar for creating Unimplemented badges that link to WebKit bugs, but haven’t done so yet.

Browser version-specific notes

Sometimes, you simply have to note browser-specific stuff, even in open web documentation. This should usually be done in the “Browser compatibility” section, with a subsection added for each browser that needs a note. For example, the browser compatibility section on the main WebSockets page has a subsection entitled “Gecko notes,” which covers Gecko-specific issues related to WebSockets, such as the fact that the constructor is prefixed.

If you do need to include browser-specific content in the middle of article text, try to put it in a call-out box or note box instead of just throwing it into the body text of the article.

The future

As we continue to build our Kuma, our new wiki platform for MDN documentation, we’re keeping browser agnosticism for documentation in mind. We have features planned to make it easier to call out browser differences and browser specific features, and to help readers filter the content based on their interests.

When in doubt… ask!

While updating or writing open web documentation, if you run into something that you’re not sure how to handle, please feel free to pop into #devmo on IRC, or to drop email to me, and ask for help. All of our happy, helpful documentation gnomes live to serve.

 Posted by at 2:04 PM

  4 Responses to “Documentation of the open web should be for everybody”

  1. Historically, MDN also has the problem that it’s trying to serve multiple audiences from the same view. That is, it needs to support Gecko/Firefox/extension/external application developers, as well as (starting from the JS reference and out to the current broader set of technologies) cross-browser open web developers.

    MSDN has a similar problem too; I see they now organize their documentation into “libraries” where a view for Windows application developer is different from the view for web-technology developers. (They also do things like compiler version, Windows version, etc.) Presumably they’re all based off the same set of docs with filters applied – I suspect things can be learned from their web service documentation.

  2. What’s that strange footnote in the compatibility table?

  3. Mook: Yeah, the Kuma wiki we’re building will have features like that to help us handle things like that better. Our current solutions there are not ideal, but at least help us get the job done when it matters most.

    Neil: What footnote is that? I don’t see one.

  4. Maybe Neil is referring to the “[1]” next to Internet Explorer in the heading row. The target for that link doesn’t exist.