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

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.