Why Specs Matter (2004)

https://web.archive.org/web/20051016203842/http://diveintomark.org/archives/2004/08/16/specs

by Tomte • 5 years ago

53 15 5 years ago

web.archive.org

ohazi• 5 years ago

The problem isn't the programmers, it's the specs. Most specs are terribly written, and are hundreds or thousands of pages longer than they need to be.

Go read the latest USB Power Delivery spec. Or the BLE spec. Or the HEVC/H.265 spec. You will very quickly want to claw your eyes out.

Ma8ee• 5 years ago

There's usually reasons for the specs looking like they do. The reasons are the same that make that beautiful pure 4 line function 150 lines after being battle tested in different environments and on different platforms for a few years.

AussieWog93• 5 years ago

I'm not perfectly familiar with power delivery or BLE, but from my experience with USB they could have just flat out omitted large parts of the spec from USB 1.0 and it wouldn't break a single use case.

I wouldn't be at all surprised if several hundred pages were added - and several million man hours wated - solely to shut up stakeholders.

OnlyOneCannolo• 5 years ago

I've read the USB PD spec. What's wrong with it? It seems ok to me compared to other specs. And yeah it's long, but different sections are for different people with different roles.

In my anecdotal experience, the problem is that many programmers just don't like working to a spec.

NiceWayToDoIT• 5 years ago

There are three kinds of people: those who can count and those who can’t.

simonswords82• 5 years ago

This blog post is true. Developers do fall in to those categories.

However, this blog post assumes that developers have been given adequate specifications!

Businesses are terrible at defining their requirements; especially large complex businesses.

People in businesses don't want to write specs because they're worried about being blamed for them being incorrect. So it's a constant "hot potato" situation.

DharmaPolice• 5 years ago

People in businesses don't want to write specs because they're worried about being blamed for them being incorrect.

I don't think it's just that - almost everyone (in my experience) finds writing specs especially boring work. With other boring work you just find someone who really likes it and pay them enough to do it for everyone (thus accountants, auditors, health & safety managers, etc). But the spec really needs to be done by someone who knows a particular domain well to have any real worth. So you can't easily farm it out.

dalbasal5• 5 years ago

It isn't just boring. It's much worse.

Taking any kind of responsibility for a spec is a fools mission. In most shops, doing specs is not highly regarded work. You don't earn much respect or career progression. You will inevitably make mistakes and have failures that make you look foolish and incompetent. You will get blame for this, and other stuff besides. Your successes will be the invisible non existence of a problem no one expected. There will be no praise, no raise.

This is true for technical and non technical "owners" of a spec. A spec might be the most important and expensive thing a department head is up to. Most determinant of department success. They will absolutely not proceed without a liability shield between them and responsibility for the spec.

Heads-I-Win-Tails-You-Lose is just an extreme condition on the spectrum of mismatched odds in organisational world. The place where successes are overcompensated and failures undercompensated is the smart place to be.

Only fools go on fools missions.

More realistically, someone is hired for the gig. They maintain a strict CYA trail, documenting who asked for what using which system... and blame/responsibility is dispersed into the system. At this point, it's boring.

dalbasal5• 5 years ago

> People in businesses don't want to write specs because they're worried about being blamed for them being incorrect

True, crucial point. This also explains a lot of developer behaviour. Specs are kind of like legal agreements. You can shake hands on a deal, and that works as long as things don't get adversarial. If things are adversarial, highly specified contracts are what you need. What you can achieve with one isn't like what you can achieve with another.

dalbasal5• 5 years ago

King of reminds me of Venkatesh Rao.

A lot of the "Blogging Golden Age" style came from these sorts of perspective. Playful, but actually trying to be real about things that are hard to be real about IRL. Sociopath is such a pre FB meme. How the world has changed.

Perhaps specialisation and expertness has something to do with these negative patterns emerging... and how compartmentalised modern companies are for most people. Black Sabbath Roadies' job is to make the concert sound like an awesome Black Sabbath concert. They have a holistic understanding of the job at hand... The "make the equipment work" parts aren't estranged from the Randy Rhoads guitar solo^ part. Without that reality backpressure, pockets of hot air seem to expand. Most programming teams are tasked with making a button for the Salesforce CS View I that triggers CS process X when thing A happens, and also do some random database stuff... This kind of setup means "specs" stand in for reality. Metrics stand in for Reality. "Randy killed that solo!" becomes a metric.

A spec is a mode of communication between humans. Inevitably, these work better or worse relative to the shared context and motivations of the humans involved.

The (nonexistent) angel category might be the most interesting, despite not existing. Less idyllically, they're just morons who have been on the path for a while, maybe dabbled in arseholery at some point... Gained context, evolved. The reason for the anti pattern is feedback. What happens the next time, and time after that. Do morons ever see the pattern? When they do, do they become disillusioned or enlightened? How does it all mature?

Where "Morons & Arseholes" dichotomies do persist, they are being reinforced rather than diminished by repetition. If they weren't being reinforced, they wouldn't be recurring patterns.

^Pedants... Don't even think about it.

Why Specs Matter (2004)

Related Stories