Why Specs Matter (2004)(web.archive.org)
web.archive.org
Why Specs Matter (2004)
https://web.archive.org/web/20051016203842/http://diveintomark.org/archives/2004/08/16/specs
4 comments
>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.
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.
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.
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.
Yeah, occasionally a process gets designed that looks like "random people who have no real incentive to do a good job put together a spec and send it to me for review/sign off." And the expectation is that it's just a quick once-over on my part so "can it be turned around some time this week?"
I always explain that in this kind of process, all the responsibility falls on me. If they write something that's incorrect and I miss it, it's never that the spec writer should have known better, it's that I reviewed and signed off on it. Which is fine, that's part of my role, but if that's the responsibility I'm taking on then the spec review is going to be scheduled as a real deliverable with real time attached to it and if you need it ASAP then you can pick something else to de-prioritize.
A good one is "we spent 6 months working with the customer to build this spec, now we're short on time, can you review this week?" Well, if it's so complex that it took 6 months to build why do you think it can be reviewed in a week?
It's this idea that spec review is just a quick review but the reviewer is then responsible for anything that's wrong with it that causes a lot of issues in my world.
I always explain that in this kind of process, all the responsibility falls on me. If they write something that's incorrect and I miss it, it's never that the spec writer should have known better, it's that I reviewed and signed off on it. Which is fine, that's part of my role, but if that's the responsibility I'm taking on then the spec review is going to be scheduled as a real deliverable with real time attached to it and if you need it ASAP then you can pick something else to de-prioritize.
A good one is "we spent 6 months working with the customer to build this spec, now we're short on time, can you review this week?" Well, if it's so complex that it took 6 months to build why do you think it can be reviewed in a week?
It's this idea that spec review is just a quick review but the reviewer is then responsible for anything that's wrong with it that causes a lot of issues in my world.
Sounds like something a software architect/designer should do or anyone who gives specific orders in a hierarchical organization.
There is always a spec. Either explicitly written down or scattered among emails, tickets and other ad-hoc communication. You can't escape it. Those who decide to do or let other people do have the responsibility anyways.
There is always a spec. Either explicitly written down or scattered among emails, tickets and other ad-hoc communication. You can't escape it. Those who decide to do or let other people do have the responsibility anyways.
Shoulds are ethereal.
>> You can't escape it.
Au contraire :) Escape from it is evident, it's clearly a hot potato. No one who should do the job would. Martyrs don't persist.
>> You can't escape it.
Au contraire :) Escape from it is evident, it's clearly a hot potato. No one who should do the job would. Martyrs don't persist.
>> 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.
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.
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.
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.
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.
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.
I wouldn't be at all surprised if several hundred pages were added - and several million man hours wated - solely to shut up stakeholders.
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.
In my anecdotal experience, the problem is that many programmers just don't like working to a spec.
There are three kinds of people: those who can count and those who can’t.
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.
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.
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.