Fog Creek Software
Discussion Board

Spec Writing Techniques

When I started at my previous job, there was no spec writing of any kind.  Requirements changed and life was bad.  Me and the other developer instituted specs.  Requirements were documented, life was better.

But I soon found I had a problem: I took too long to write specs.  I found myself getting really detailed and way too careful about each and every word I used.  I'd write them and rewrite them like I was composing a book or a legal document, until I felt they were 'just right'.

If I tried to be more general, or tried not to care about exactly how things sounded from an english / writing / readable standpoint, the spec failed because either:

1. The customer would abuse it to insert new functionality not originally intended

2. The customer wouldn't like the spec in the first place, and would go elsewhere for business

Obviously part of the problem was we took on part of the role of the sales guys.  A potential customer would come in, tell us what they want, we would spec it (in terminology that the customer understood, but we also got detailed enough to quote times), and the customer would decide if they wanted to pay whatever the sales guys randomly assigned to our quoted time.

But spec'ing was still seen as "non billable time" by management, and so the longer we spent doing it the worse we as developers looked.

What I'm getting at is, what have you learned about the art of spec writing with regards to various target audiences?  Do you even try to use complete sentences with proper grammar?  Bullet lists?  What techniques do you use to balance minimal writing time with sufficient detail?

Monday, February 17, 2003

Joel has an excellent article on writing specs.

Prakash S
Monday, February 17, 2003

The Deadline:

has some good observations on specs.

Monday, February 17, 2003

>>But spec'ing was still seen as "non billable time" by management, and so the longer we spent doing it the worse we as developers looked.

In my mind this is one of the most valuable parts of the exercise and so should be paid for. If you don't charge your customer for it then they will think it has no value.

Tony E
Tuesday, February 18, 2003

Hint to management: Offer a "detailed specs" for a price, thus making "writing specs" billable.

I bill my clients for that, no question, and I believe -and so does the client- that specs are the most important part they need.

Once you have the functionality is spec'ed (???, we should learn grammar too!), a programmer can write in his native language. Actually, the programmer just translates the Specs from American English to ASP (or ___insert your favorite here...).

Wednesday, February 19, 2003

You could try maintaining two sets of specs:  High-level customer requirements, and related low-level implementation details.

A high-level requirement might specify, "The user can log in."

Each high-level requirement would have low-level requirements such as, "If the user isn't logged in, the navbar on every page has a 'Login' link." and "If the user fails to log in, s/he is redirected to the login page with a message in red specifying the nature of the error."

With this system, you can satisfy with the customer that all the high-level requirements are satisfied, then hash out the low-level requirements as you need to.

Brent P. Newhall
Wednesday, February 19, 2003

*  Recent Topics

*  Fog Creek Home