I tried thinking of all techniques I have seen or have used in making great specs. I put all those techniques in a crucible and boiled away everything until only one principle remained. Here it is:
“Specs must be readable”
And as obvious and trivial as it seems, that central message gets lost.
Why is it critical? Because if your audience can’t successfully go through the document and understand what is written, any design or discussion that stem from that spec is nonsense – the participants aren’t even on the same page to have a meaningful discourse.
So how do otherwise well-meaning and intelligent people sabotage their specs. Here’s a list:
- Too many words
- Underestimating the audiences ability to misunderstand
- Confusing spec writing with the writing of fine literature or a research papers
- Not understanding how their audience uses a spec or what they need from a spec.
- Using text when a table or list or a diagram would be much better choices
- Poor ability to structure ideas on the page or in their own mind. If the author is confused, what hope do the readers have?