Jeff Davis recently examined the question of how much detail you should provide in a design specification. As you might expect, the article provoked some heated discussion here at Builder.com. Among the topics up for grabs were:
- Does the QA team function better with more or less detailed specs?
- How important is it to get client signoffs during the spec-writing and development process?
- What are the real differences between functional and design specifications?
You can check out the full discussion here.
It’s clear our members care a good deal about specifications. After all, as a system architect or senior developer, you spend a good deal of your professional life either writing them or interpreting them. In the coming months, you’ll be seeing a lot of articles here at Builder.com analyzing best practices for specification documents.
But right now, we want to talk about worst practices.
Send us your best examples of bad design instruction
A while back, on our sister site TechRepublic, we asked Help Desk and Support techs to e-mail us their best examples of truly egregious behavior by their end users. We compiled the best dumb-user stories in a single document for our download library. It remains one of the most popular downloads TechRepublic has ever created.
We want to do the same thing for design specs. E-mail us the best example of bad spec writing you can remember. We’ll compile the best (or worst, depending on how you look at it) responses into a single document and make it available for download.
To provide some extra incentive, we’ll draw some respondents at random and give them a free Builder.com golf shirt.
Here are the rules:
- We don’t want to see the complete spec, just the offending portion.
- If you don’t have the spec anymore, just paraphrase from memory the section you want to nominate.
- We don’t need to know the name of the organization or even the details of the project; please remove all such references from the section you send us.
- In addition to the instruction, please send a brief paragraph explaining the circumstances and why you found the instruction so muddleheaded.
Again, please send us an e-mail. Give us your best shot!