How detailed do your specs have to be?
That depends greatly on who the target audience for the spec is.
A rule of thumb I use is to make the specs sufficiently detailed that someone one notch less skilled than I am could read the spec and have a good chance at implementing whatever the spec describes. As a rule of thumb, it's worked pretty well.
Two book recommendations to help make your specs readable:
- Lyn Dupre, Bugs in Writing (Revised). Dupre is a technical editor who has handled a number of heavyweight technical authors (Patrick Henry Winston, Carver Mead). She has a great ear for the patterns of mistakes that technical folk tend to make.
- Joseph Williams, Style: Toward Clarity and Grace. Unlike teachers who focus attention strictly on sentence structure, Williams shows how to link sentences together into a readable whole that will draw a reader onward. A friend TA'd for Williams at U. Chicago, and has great stories about how Williams would take some piece of recent bureacratic nonsense and iteratively refine it into something readable. Williams doesn't directly address technical writing, though everything he talks about applies. Williams also delights in tying strict grammarians in knots with counterexamples.