When Guidelines Should Be Descriptive or Prescriptive

Published on Sep 13, 2008 (updated Oct 20, 2024), filed under development, html, css, quality (feed). (Share this on Mastodon or Bluesky?)

This and many other posts are also available as a pretty, well-behaved ebook: On Web Development. And if you’re only interested in a robust overview on coding guidelines, check out my little book on it: The Little Book of HTML/CSS Coding Guidelines (updated).

Every time I’m putting up guidelines or conventions one of the decisions I need to make is whether the guidelines, or which parts of them, should be descriptive (positive) or prescriptive (normative). For coding guidelines this could mean the difference between, say, “the markup should be valid” and “the markup must be valid” (think RFC 2119).

The question is when to recommend or describe something to be followed, and when to force and prescribe. In my mind this decision depends on three factors:

The goal. Is there a need to sensitize and establish a particular mindset and process first, and is there sufficient time as well, or is it desirable to quickly enforce certain rules, even when the results are already solid? Establishing a mindset suggests to go for recommendations first, whereas enforcing something means to come up with clear requirements.
The situation. Is everybody doing well, or is the situation rather bad? If it’s going well, then an approach based on strict rules might be best in order to create support for everything that’s already been achieved, and the guidelines may only mean a written testament of formerly unwritten laws. If the situation is bad, then descriptive guidelines and recommendations may work best to gently push into the desired direction.
The priority. Low priority issues don’t need to be treated with strict rules right from the bat; they allow for some flexibility. Only critical issues may get all the attention. (For example, coding guidelines that require lowercase letters for hex color values but leave it open to use valid CSS exhibit an “interesting” sense for what’s important.)

Let’s take the valid markup example from the introduction to make decisions for the coding guidelines of a few imaginary companies:

Company 1, the goal: Have valid output be the prerequisite to develop and improve the company’s websites. Changing the guideline? “The markup must be valid.”
Company 2, the situation: suboptimal. Nobody validates, valid code is a coincidence. How to handle a guideline about valid markup? Take the gentle approach: “The markup should be valid.”
Company 3, the priority: Low, after observing that the company uses elements according to their purpose, and that there are few accessibility issues. Changing the guideline? That then depends on the value of the goal, the philosophy, and quality ambitions; if it was me, I’d go for “the markup must be valid.”

As we can see, the “descriptive vs. prescriptive” problem is not just one for linguists talking grammar. It’s of relevance for our industry, too. I may have missed opportunities to make better points, but I hope that the main one came across, namely that “descriptive vs. prescriptive” is something we need to keep in mind.

This is likely to be the last post I publish during my stay in the U.S.—I’ve been taking a few days off—but the next one should be out in one and a half weeks. Consider taking a very short survey if you didn’t already (thanks to all who have already casted their vote!), and enjoying some of the posts from the past!

About Me

I’m Jens (long: Jens Oliver Meiert), and I’m a web developer, manager, and author. I’ve been working as a technical lead and engineering manager for companies you’ve never heard of and companies you use every day, I’m an occasional contributor to web standards (like HTML, CSS, WCAG), and I write and review books for O’Reilly and Frontend Dogma.

I love trying things, not only in web development and engineering management, but also in other areas like philosophy. Here on meiert.com I share some of my experiences and views. (I value you being critical, interpreting charitably, and giving feedback.)