The Old Joel on Software Forum: Part 3 (of 5) - Specs

Specs - what is a good one?

Hi:

What does it take to have specs that are considered great by developers?

Are there examples online we can look at?

I have often heard developers complain about the quality of specs.

Has anyone been happy with their specs and can give reason why?

Naturally specs will vary greatly depending on the project. Lets assume that the product would be a web-based application with considerable back-end development work.

Ram Dass
Friday, October 31, 2003

My own preference for specifications derives from design by contract principles popularized by Bertrand Meyer in his Eiffel language. This approach captures the expected behavior of components via (mostly) executable assertions in the code. There are also a set of rules which constrain these assertions so that the system is logically consistent. Finally, there are good principles for employing these concepts effectively in practice. There is also a visual modeling language that provides rich support for this material called the "Business Object Notation" There are several good books on these topics, and the Eiffel web site has a lot of information on it:

http://www.eiffel.com/

On the data side, an approach with similar rigor is Object Role Modeling and the related practice of Conceptual Design. The work of Terry Halpin is probably the best reference on this subject. This approach specifies the structure of data in a powerful, logical manner. Check out the official website for good material:

http://www.orm.net/

Combining these approaches, I've never seen a better way to capture software specifications. You can augment these with other material, but they are very powerful, even on their own.

DBC
Friday, October 31, 2003

I know these are only a very small subset of specs but the specs I like best tend to be protocol specs. I guess it's because they have to be very precise and, as such, are usually a joy to work from. Things like an ISO8583 message spec, or the POP3 or SMTP specs are nice. The OBEX spec is particularly nice (even though there are a couple of pieces of the protocol design that I don't like...) and comes with a test spec as well... The lack of ambiguity makes writing the code easy.

Len Holgate (www.lenholgate.com)
Friday, October 31, 2003

Check out Joel's five part series on writing great specs in the Joel on Software archives.

Henry Ford II
Friday, October 31, 2003

Those ones were inspiring at the time:

http://web.archive.org/web/20020126152639/developer.arsdigita.com/doc/acs-workflow/requirements.html

They went bust but they were sharing a lot of insightful stuff.

Philippe Back
Friday, October 31, 2003

specs need to answer "why".

so a spec which says:
field A is numeric.

isn't very meaningful because you can look at the code and figure that out. (yeah, the spec might come first, but often doesn't, or it might need to change and no one is sure if it's safe to change field A).

however:
field A is numeric and represents the order number in the foo order tracking system

is more useful, because it explains WHY it's numeric, and not a date or a string or some other thing, like a guid which is used for order numbers in the bar tracking system.

mb
Saturday, November 1, 2003

If we're talking about functional specs I love then written treating me as very dumb person. Without over use of jargon, operating with metaphors which everyone understands. I want this kind of spec to provide me with 97% of info to needed to understand the plan, instead of sending me to outside sources, which I not likely going to find or understand.

If we're talking about technical specs - I like them detailed. The more - the better. I can even handle the jargon then. I want them specify everything down to the smallest bit, including that to do when electricity gets cut off.

In both cases I want spec to be carefully re-read by the author and author to have clear picture of what we're going to achieve.

Vlad Gudim
Tuesday, November 4, 2003

I agree with MB. Spec should provide INTENT of the system.

Remember that the spec is just ONE part of the design process. Often times people "skip a step".

You should answer:

WHAT result do I want to have
(Be able enter and retrieve sales orders. View history of sales, etc.)

WHY is this important

HOW will we accomplish it.

BAD specs skip right to the HOW. No amount of "HOW" will make up for a missing WHAT and WHY. Conversely, a crappy HOW just makes for expensive code. You can still have a successful product if the first two are properly addressed.

Entrepreneur
Wednesday, November 5, 2003