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 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 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 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!