Standards: Or, How to Program Engineers

  1. Standards specifications are like computer programs, specific instructions intended to be executed by an implementing engineer.
  2. Engineers are the worst and most unreliable runtime platform ever imagined.

These aren’t just documentation

At first, a technical standard seems like it’s a form of documentation: you are writing down what goes into a protocol or system, why it’s there, and what every bit means. While that’s true on the surface, it ignores an important point: you are writing a standard because you want different people, who aren’t talking to each other, to implement things in a way that the different parts work together.

If it can go wrong, it will

Even with the best standards, people are fallible and they’re going to get things wrong. This isn’t necessarily malicious. In fact, the vast majority of implementors want to follow the spec and do what it says. But more than that, they are implementing a standard because it does something that they need done but don’t want to invent themselves. Engineers are great at coming up with creative solutions to problems, but they’re even better at copying someone else’s solution to a problem they don’t want to care about anymore. And that is where standards come in.

  1. The title. Well, most of the title. They probably searched a couple keywords and if those are in the title, we’re done here.
  2. The examples. These are far and away the most important portion of the standard, because implementors are going to either copy these directly or tweak their code until it looks, to their eyes, like the examples.
  3. Any bulleted lists around the examples. After all, these probably show additional options that might not be in the examples. Developers will look at these if the examples don’t do exactly what they want.
  4. Any actual text. This stage is only reached when things are starting to go wrong. By this point they’ve probably already added a bunch of stuff to the protocol and are trying to figure out why that’s breaking something.

Remember who is implementing

The final thing about a standard is that most engineers will never read it, at all. Most developers are going to approach your standard through library or vendor documentation, or webpages that describe in plain language what’s going on with the protocol. The list above is only for the kinds of folks who need to go back to the spec itself, which includes the authors of those libraries and the engineering teams at those vendors that everybody else uses.

How a specification author can help

I have found it to be an incredibly helpful exercise to treat the instructions within a specification as code from the perspective of a naive implementor, someone who doesn’t have my background or goals when approaching the spec text. Take the spec text and do what it actually says. Not what you meant for it to say, not what you wanted to be able to do with it, but just what it says. It can be enlightening to see the gaps and assumptions that get made here.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Justin Richer

Justin Richer

514 Followers

Justin Richer is a security architect and freelance consultant living in the Boston area. To get in touch, contact his company: https://bspk.io/