What makes a good spec? [closed]

Question

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 1

Good specs should contain requirements that are measurable and verifiable. When looking at each requirement, you should be able to easily answer the question, "How can I prove I have fulfilled this requirement?".

Answer 2

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

Answer 3

It also helps if you start by stating the goal the user has or what the global idea of a certain function is; rather than filling in the exact implementation. This always feels to me like narrowing down the open mindedness or using less creative (more usable) solutions. So you should keep "all options open".

Example Your writing a software to measure "X".

Instead of stating: There has to be a start button and a save button.

Use: The user has to be able to start a measurement and save it.

Why? Because in the first situation you already determined what the solution has to be, while the second situation gives you flexibility on how to implement something. Now this may seem trivial, but I have the feeling "programmers" tend to think more in solutions rather than in problems (or situations). When you add more functionality this becomes more obvious, because then it might have been better to use a wizard or automate the process, but you already narrowed the idea's down to using buttons.

Answer 4

I think writing "Use cases" should save you bunch of pages

Answer 5

As someone who develops bespoke software for clients, the best spec is the one which the customer has signed.

It doesn't matter how refined your spec is - if the customer hasn't explicitly agreed to it in writing, they'll change it and expect you to roll with their changes seamlessly, wrecking your beautiful architecture...

Answer 6

A blueprint that describes all of the critical information necessary for the implementation, but doesn't waste any effort on describing all of the trivial or obvious information that is also necessary.

It should just be enough information to insure that the implementation is "as expected", without providing too much additional noise that isn't necessary.

In practice, most people get this wrong, as they focus on the easy stuff (which is the least necessary) and shy away from the hard stuff (which is what you really really want to lock down). I've seen way too many 2 inch documents that completely and utterly miss the point, and very few 3 page ones that hit it dead on.

Specs don't have to be long, they just have to contain the right stuff!

(hint: if the programmer didn't look at that page while coding, it probably wasn't required)

Paul.