What makes a good spec?

specifications
Candidasa picture Candidasa · Dec 18, 2008 · Viewed 11.4k times · Source

One of the items in the Joel Test is that a project/company should have a specification.

I'm wondering what makes a spec good. Some companies will write volumes of useless specification that no one ever reads, others will not write anything down because "no one will read any of it anyway". So, what do you put into your spec? What is the good balance between the two extremes? Is there something particularly important that really, really (!) should always be recorded in a specification?

Answer

Robert C. Barth picture Robert C. Barth · Dec 18, 2008

The best spec is one that:

  1. Exists
  2. Describes WHAT, not HOW (no solutions)
  3. Can be interpreted in as few ways as possible
  4. Is widely-distributed
  5. Is agreed-upon as being THE spec by all parties involved
  6. Is concise
  7. Is consistent
  8. Is updated regularly as requirements change
  9. Describes as much of the problem as is possible and practical
  10. Is testable

Related questions

How to encode the filename parameter of Content-Disposition header in HTTP?

Web applications that want to force a resource to be downloaded rather than directly rendered in a Web browser issue a Content-Disposition header in the HTTP response of the form: Content-Disposition: attachment; filename=FILENAME The filename parameter can be used …

Read More
What does the @ symbol before a variable name mean in C#?

Possible Duplicate: What's the use/meaning of the @ character in variable names in C#? I understand that the @ symbol can be used before a string literal to change how the compiler parses the string. But what does it mean when …

Read More
Java's L number (long) specification

It appears that when you type in a number in Java, the compiler automatically reads it as an integer, which is why when you type in (long) 6000000000 (not in integer's range) it will complain that 6000000000 is not an integer. To …

Read More