Ask HN: Well written / designed “spec” document?

1 points by akor 6 years ago | 1 comment

Does anyone have examples of a well written spec document and if available approx. how many hours went into coming up with it? I heard Seth Godin talk about how they did a spec so good they just handed it off to a development shop and let them roll with it but my experience has been far from that. I know part of the issue is internally we're not spending enough time developing the spec but I'd like to see some well designed ones as a frame of reference for how things should be done. TIA.

djhaskin987 6 years ago |

Well, I have written this: https://git.sr.ht/~djhaskin987/onecli/tree/master/doc/rfc.rs...

It took me a couple of days to write. Does it seem clear to you? Would you be able to take it and run?

My guess is that you wouldn't because I haven't tested and made sure that the spec was clear.

Atul Gawande in his book "The Checklist Manifesto" makes the point that specs (in his case, checklists) are like programs in that they need to be tested and tweaked many, many times over the course of several iterations before they are clear, actionable, and useful.

Thinking of it this way, a spec is like a human program: it is telling the human what to do, or at least (as in declarative programming) what is wanted. like a normal program, it needs "work" (revisions, having a different person / "compiler" read the work and comment) before it shines, just like any writing.

Or you could come back from reading that spec that I linked to and think "Wow this sounds clear, I could implement this." In which case I'd be wrong, because I wrote that in one go.