Mar 062011

As part of our ongoing effort to make our documentation more globally useful, instead of implying that our web content is Firefox specific, we’re going to start to get rid of our old “Requires Gecko X” banners at the tops of pages covering web standards in favor of compatibility tables. Some articles already have them, others don’t, but we’re going to start using them more.

This coming week, one of my tasks is going to be to try to create a MindTouch template that, given information about each browser or engine, will automatically lay out and generate a compatibility table. To do this, I’m going to make use of MindTouch’s support for named parameters, so that you can do something similar to this:

{{CompatTable(gecko:{version:”1.9.2″, note:”Was called -moz-foo before Gecko 2.0.”}, safari:{version:”4.0″, note:”Some notes.”}, ie:{version:8})}}

This would generate the table, automatically filling out any rows for unmentioned browsers with empty rows. For example, the table generated by the above template might do something like this:

Browser Version Available Notes
Gecko 1.9.2 (Firefox 3.6) Was called -moz-foo before Gecko 2.0.
Internet Explorer 8
Safari 4.0 Some notes.

Notice that there are rows for Chrome and Opera even though they weren’t specified. This ensures that the tables site-wide will be consistently formatted. We can add new browsers to the table by simply adding them to the template, and updating articles at the appropriate times.

The main issues that need to be decided upon before actually writing this template:

  • Can we simply have a “webkit” version number and figure out which version of Chrome and Safari that applies to?
  • Can the same “webkit” version be used for mobile versions of Safari? I don’t think it can. Do any mobile versions of Safari have enough market share (and are different enough) to warrant mentioning explicitly, other than iOS?

By using named parameters, we can be much more flexible about leaving out bits of information, plus we can add more fields later without having to recode all past uses of the template. That said, if anyone has thoughts on additional information the template should initially be designed to support, please let me know.

 Posted by at 8:46 PM

  12 Responses to “Browser compatibility and documentation planning”

  1. Maybe this is unavoidable, but it seems very weird to have “Gecko” and then Chrome, IE, Opera, etc … I think Firefox | 3.6 (Gecko 1.9.2) is a more sensible way to do this.

    Also, you should put Firefox/Gecko first :-P

  2. The tables definitely need to have the engine names in a clearly separate column (so gecko is analogous with Trident, Presto, Webkit and KHTML), with 2 columns for “Desktop version” and “Mobile version” instead of the one “version available” column.

  3. I’d suggest allowing multiple versions for each browser, and showing a row for each with the single name to the left of the first row. That would allow writing more detailed compatibility notes, such as support in a particular version and non-standard support in an older version.

  4. On an unrelated note, your blog system seems to reject as “spammy” any comment with “anonymous” anywhere in the name or email fields.

  5. I don’t think we can use a simple WebKit version, even on desktop. Chrome and Safari use different components for networking, painting and JavaScript.

    I think a template like this should take mobile into account from the beginning. At least Android, iOS, Blackberry and Opera (mobile and mini). Use a JS tab system to swtich between desktop/mobile views.

    Also, it’s not clear if the empty rows mean “no support” or “not yet tested”. Maybe another colon with a “good”, “no good” icon could make that clearer.

  6. Great move, looking forward to seeing it action.

  7. Kyle:

    Well, by using “gecko” as the keyword, the table generator can be adjusted to output the appropriate information in whatever format we see fit, since we can have the template adjust the output intelligently.


    That’s a good call.


    Yeah, we could do maybe a versions: parameter, which would take multiple inputs, such as versions: [{version:"1.2", note:"Some note."}, {version: "1.6"}].


    Yeah, that’s what I suspected as well re WebKit. Too much fracture there. We can do something to indicate the difference between “no information” and “not supported” easily enough, I think.

    Lots of good feedback here! Just what I was hoping for!

  8. For the granularity of support, here are the different value used in Quirksmode for inspiration:
    I think that there are at least two pieces of informations that may need to be separated: support and conformance. For instance, in the case of IE8 for Object.defineProperty (, the method is present but isn’t standard at all. So, someone performing feature detection will notice that the method exists. However, a second test is required to test partial conformance.
    Moreover, for CSS, the display property is supported everywhere. Still, in IE6, the ‘fixed’ value cannot be used. In IE7, ‘inline-block’ has some non-standard restrictions. In neither IE6 nor 7 the table-layout values are available.
    I think it is worth for the template to be able to encode this kind of information (in a more “formalized” way than in notes).

    Since we’re dealing with standardized technologies, would it make sense to add another row (or whatever formatting) with the refering standard (ECMAScript, DOM Core, DOM Events, CSS 3 module blabla…), the standard version and a link to it? The template could contain the links for a certain number of specs.

    Maybe a link to other vendors official documentation when applicable?
    Maybe a link to tracking bug (may only apply to Gecko&Webkit browsers)?

    There might be a need to mention when feature support has been dropped. I don’t think it’s the case, but there might have been some stable browsers version with Websockets and later which dropped support because of the protocol security issue. Experimental features may have been dropped too sometimes.

    There might also be a need to mention vendor prefixes when there are some (once again in a more “formalized”/query-able than just notes).

    Wait… what? Have I heard that right? Browser compatibility will be the topic of the next doc sprint in 3 weeks! That’s an awesome idea ;-)

  9. Will it be possible to include links and other wiki markup inside the notes?

    Safari and Chrome should be next to each other, since they share a layout engine and will often have the same notes.

  10. Jesse: I was thinking about that last night. One downside to using a template like this is that including links and the like in the notes is slightly tricky. You can do it but the syntax is a little odd. Some experimentation will be needed to see if using a template will work for us. I think it would help improve consistency as we move toward more global usage of compatibility tables, but we’ll have to try it out in some tests to see if it will actually work for us.

  11. Shorthand syntax for tables is tough. I’d also love to see links available here, as I know I have spent a good bit of time to track down exactly when a feature landed in a browser. Would love to keep record of that evidence. :)

    Chrome and Safari, while they share WebKit, differ in the DOM, CSS Transforms, audio/video, and a whole bunch of other stuff. I think, in general, it’s better to talk of the 5 browser landscape than the 4 1/2 engine landscape.

    One thing I keep thinking about is the success of — the compat table indicates the current release along with a few ahead and behind. While it’s clearly scope creep, if we’re about to beef up the compatibility table story, we should nail the design now rather than afterwards. :)

    (Caniuse also summarizes the “readiness” % for each feature based on browser market share data. It feels a bit superfluous for MDC, but gosh it is handy.)

  12. I’d like to enforce the idea of encoding when browsers stop supporting a feature.
    A couple of days ago, a bug has been filed to ask for the end of __proto__ support: . __proto__ has never been standard, but its wide adoption made it a de facto standard used in a couple of libraries like prototypeJS or fuseJS.