The support matrix

Six weeks into a build, somebody forwarded me a screenshot. The client’s finance director had opened the staging site on the machine in the back office and the layout had come apart down the left-hand side.

The question attached to it was “is this a bug,” which is a completely reasonable question, and I did not have a reasonable answer. Because the honest answer was “that depends on whether we support that browser,” and nothing anywhere in the project said whether we did. Not the proposal, not the estimate, not the ticket, not a wiki page. So the answer got decided in a corridor by me, on the spot, under mild social pressure, which is how I have decided this on approximately every project I’ve ever worked on.

I fixed it, obviously. You always fix it. That’s the point.

Everything is supported until you say otherwise

Here’s the thing I took a while to understand, and it isn’t technical at all.

If you never write down which browsers you’re building for, you have not left the question open. You’ve answered it. You’ve answered “all of them,” because that’s what a client reasonably infers from silence, and honestly it’s what I’d infer too. Nobody buys a website and assumes it comes with an unstated list of machines where it doesn’t work.

So the absence of a promise reads, to everyone who isn’t you, as a promise of everything. And then every screenshot from every old laptop in every back office is a defect, and defects are free, because they were in scope by implication and nobody agreed a price for them.

The absence of a promise reads, to everyone who isn't you, as a promise of everything.

I wrote something a couple of years ago about IE8 being a client rather than a browser, which was really about the same thing from the other end: browser support is a commercial decision that keeps getting filed as a technical one. The support matrix is just the filing done properly.

Grading on a curve

The instinct is to write a list of browsers with ticks next to them, and that falls over immediately, because “supported” isn’t one thing. A site can be perfectly usable somewhere I’d never promise pixel-fidelity.

Yahoo published a thing called Graded Browser Support about a decade ago and I’ve been quietly using its shape ever since. Three tiers:

Grade A. It looks right and works right, we test it every sprint, and a visual difference is a bug. This should be a short list. On most of my projects it’s current Chrome, current Firefox, current Safari, current Edge, iOS Safari and Chrome on Android.

Grade B. It works. Everything is readable, every form submits, every link goes where it should, and it may not look identical. Rounded corners might be square, a grid might be a stack, an animation might not happen. This is where IE11 lives on nearly everything I build now, and it’s where the old Android stock browser lives, and it’s the tier that does all the actual work in this document.

Grade C. We don’t test it and we don’t fix it, and it gets served HTML and CSS that a browser from 2004 can cope with, because HTML degrades on its own if you haven’t fought it.

The reason three grades beats a list of ticks is that Grade B is the honest answer to most questions and a tick box can’t express it. “Does it work in IE11” has the answer “yes, and the cards are in one column,” and that sentence is the whole negotiation.

Check the analytics, not the blogs

Not from me, and not from a blog post about what’s dead this year. From the client’s own analytics, which I ask for before I write anything, and which almost nobody has looked at.

Current share is the least useful number in there. What I want is the trend over 12 months, because a browser at 2% that was 4% last year will be 1% by the time the site has been live six months, and you’re building for that window rather than for today. IE8 halved roughly every year for as long as I watched it, and Microsoft finally stopped supporting it, along with 9 and 10, a year ago this month, which took the argument out of my hands entirely and I was glad.

And then the bit the numbers won’t tell you, which is who those people are. I’ve had a client where the 3% on an ancient browser was one hospital system on a locked-down build, and they were the single largest customer in the business. Percentages are a poor proxy for revenue and a terrible proxy for who phones you.

It has to live in three places

A support matrix in a document nobody opens is the style guide problem again, and I have learned that lesson enough times now. So it goes in three places, and it is the same matrix in all three.

In the proposal, in a sentence a non-technical person can read and sign. Not a table of version numbers. Something more like: current versions of the major browsers get the full design, IE11 and older mobile browsers get a working site that may look simpler, anything older than that gets readable content.

In the test plan, as the list you actually open before you ship. If it isn’t in that list you don’t test it, and if you don’t test it you can’t promise it, so the list and the promise are the same list.

And in the repo, machine-readable, because half of the toolchain will read it for you now.

package.json

"browserslist": [
  "last 2 versions",
  "ie 11",
  "> 0.5% in GB",
  "not ie <= 10"
]

JSON

Autoprefixer reads that, so the prefixes I ship are derived from the promise I made rather than from a preset somebody copied in 2014. That’s the part I find genuinely satisfying: the commercial decision and the build output stop being two unrelated things that drift apart over 18 months.

Not a magic wand

It doesn’t stop the screenshot arriving. It just changes what happens next, which is that I have a document to point at, and the conversation becomes “that’s Grade B, here’s what Grade B means, do you want to move it up and what would you like to drop to pay for it.” That’s a normal conversation between adults about money. Without the document it’s me looking like I’m making excuses.

It also doesn’t help if you write it and never revisit it. A matrix is a snapshot of an audience, and audiences move. I’ve started putting the date and the source of the numbers right in the document, so that in a year’s time it’s obvious it’s stale rather than authoritative.

And it can’t be a wish. If you write Grade A and don’t test it, you’ve written a lie with a table around it.

Twenty minutes in week one

It’s one page. 20 minutes, at the point in the project where everyone is enthusiastic and nobody has anything to defend yet, which is exactly when it’s easy to agree and exactly when nobody thinks to.

I don’t think I’ll ever get it into every proposal. But I’ve now got it into enough of them to notice the difference, and the difference is that I stop having opinions about browsers in corridors.