Kilian Valkhof

Prescriptive software is better than descriptive software

For a while now I’ve been telling people that I want Polypane to be prescriptive, not descriptive. In this article I want to expand on that and explain what I mean when I say “prescriptive”.

I usually explain it like this: there is no shortage of tooling that will tell you everything you do wrong when building sites (in fact, some even warn you that they may hurt your feelings!) but I want to have tooling that tells me what I should be doing instead, and how to fix the issues it found. That’s what I mean with prescriptive software.

If you prefer, you can also call it opinionated software and that’s fine as well. I think software should be opinionated. Throwing everything in a huge settings panel or configuration file and calling it “choice” or “not imposing your preferences” is a product development failure.

That’s a bit harsh, sure. But you wouldn’t hire a consultant that only tells you what’s wrong but not how to improve it. Similarly, software you “hired” for a specific task should do the same.

You don’t know what you don’t know

As developers we need to keep a lot of different things in mind. Just a few of the things a front-end developer needs to keep in mind when it comes to CSS beyond mastery of the language itself:

Cross-browser differences, color contrast accessibility, caching strategies, loading strategies, loading performance, motion design, typography, graceful degradation.

Those are just off the top of my head, I’m sure I can come up with more. And that’s just one aspect. This leaves out HTML and JavaScript, Interaction paradigms between different devices, SEO, Usability et cetera. And all of those have their own list of things to keep in mind.

In short, being a front-end developer means you need to know a lot about a lot. That’s not a complaint. In fact it’s one of the things that make front-end so exciting to me.

But every developer has gaps.

I don’t think we should expect developers to be experts in all areas and ideally your team covers all bases between team members, but that’s not always the case.

You can either pretend and write software that tells devs something’s wrong and expects them to know how to fix it, or you can tell them what to fix and how to fix it, so they can get on with their work.

Help devs where they are

To expand on that point: because devs already have so much on their plate, the choice they have to make is either “stop working and learn about this new topic enough to be able to fix whatever issue came up” and “continue working on the thing I do know” and guess what, they’re gonna continue working. Devs usually are evaluated on the work getting done, not on what they learned along the way.

Prescriptive software helps devs where they are while they’re doing the work. You avoid context switches and you avoid training devs to ignore the very issues your software tries to help with.

The choice is between your rules and no rules

If you’re a tool developer you’re so much more aware than most devs that there’s nuance to whatever you’re developing software for. There’s more than one way to skin a cat!

But anyone that has ever implemented ESLint in their organization knows what a shitshow it is. Endless debates about each and every potential configuration. “Yes we want to use the AirBnB config, but we really need to change the semicolon configuration, and eqeqeq is really not going to work for us so…” Cue discussion.

Anyone that has ever implemented Prettier in their organizations knows that it went a whole lot smoother. Prettier has formatting rules. They get applied. End of story.

ESLint is a blank slate. Prettier is opinionated.

ESLint won’t do anything until you tell it to, but Prettier has its own rules and while you can configure it, you don’t have to. It’s going to impose its own standards if you don’t.

Prettier has one big choice: “use it, or don’t use it”.

There is no big choice for ESlint. There’s a hundred different small choices. And while devs like their discussions, after 75 of them you’re just done with it. ESLint implementations often stagnate, or adherence drops because there never really was consensus but people just got tired and acquiesce.

If you’re a tool developer you’re intimately aware of the nuance in your choices. Your audience probably isn’t. (And that’s fine! They already know a lot of other things). Pushing that choice to your user will change the question from “nuanced option A or nuanced option B” to “should this be dealt with or not”. The no-deal choice is infinitely easier to make, nuance be damned.

So if you’re a tool developer thinking “who am I to decide?” then consider this: The choice is between following your advice, and doing nothing. They hired your software to do a job.

What it looks like in practice

A very clear example of prescriptive versus descriptive is the Polypane contrast checker.

A year ago, I was working on global Corona checking project together with a ton of other volunteers, using Polypane to make sure the project was as accessible as possible. One of the things I was checking was color contrasts. I got frustrated that Polypane was just pointing and saying “Hey that’s wrong”. If I could calculate which color didn’t have enough contrast, surely I could calculate how much darker or lighter it should be to have enough contrast.

So I implemented that the next day and it made a huge difference. I could just stay in flow in my browser and text editor, rather than opening a design tool to pick colors and an online contrast checker to test those colors.

The tool gave me the solution for the issue it encountered, and I could just get on with my work without leaving my current context. It was prescriptive in what it thought should be done.

All I needed to do was follow it.