Clear questions and runnable code
get the best and fastest answer
A good spec is a joy and a necessity for getting a large scale project right.
A fair part of the time of engineering a project should be spent on the spec, getting queries from both sides sorted out. Once it's been done to death, and both sides agree it's a feasible and accurate document, comes the initial design.
After finishing something that seems to represent exactly what was in the document (a real spec shouldn't be wooly, so the design should be an accurate representation), you go to prototype.
Prototyping is just a quick hack of the design in a rapid development language. This is what is demoed, and the originator of the spec should be able to say "Yes, this is exactly it" or point out in the spec what has been misinterpreted.
However, at this point, a 'customer' should not be turning round and saying "Oh, we just thought it'd be really neat if this supported this whole new basic philosophy!".
If they do, an appropriate response would be "Yep, it'd be really great if it did, but it doesn't.".
Man goes to car showroom and says "I'd like that model of car, in red, with heated windows and low profile tyres please. I'll order now.".
Dealer then promptly orders car which turns up.
Man then turns to dealer and says "But it doesn't have tank tracks on it for doing serious offroad! It'd be really great if you could just put them on for me now at no extra cost.."
In short, they've asked for something. They've been given proof that their product is there, and they've got what they asked for.
Once the spec is done and dusted, it's a contract. Allowing one side of an agreement to go changing it and not the other is rather unfair (how would the customer feel if the developers turned round and said "Hey, neat idea to really make this thing run fast! We're removing the user interface for performance optimisation"..
However, sometimes, changes aren't that bad. These days, there are CASE tools for development (see a few case tools here).
If the request comes in early enough, changes may be made to sections of the model, and the code base regenerated from the design. In most cases, only sections will require redesign, and as long as all internal interfaces are not altered, the majority of coding is still valid.
My personal opinion is that the Spec document is the most important part of the process. If that's wrong, then everything else will follow.
Once it's done, it's done.
If someone starts saying "We want this feature", they really should be hearing the reply "Well, when the next version is released...."
An example of bad use of spec was in my time working for a very large UK Telecoms company as a contractor.
In one short meeting, I was requested to provide an access mechanism to a remote tool, and allow logs to be accessed from it an analysed. In almost those exact words.
When asked if I could have a real spec document, people went quiet, said they didn't have the time, and that it was a 'waste of resources' to do that. Which irritated me no end.
Then I was asked how long it would take to do. Given it wouldn't take long to write the code to access the tool in question, tie it to a database, and check it worked, I gave time as about 3 weeks including rough testing.
Everyone agreed to this, and off I went.
Almost as soon as we left the meeting, people started coming up and saying "Oh, and it needs to do this too."..
Needless to say, the original deadline wasn't allowed to be moved, as I'd said it would take three weeks to build. But the company was allowed to shift the goal posts.
The first version was released 2 weeks late, due to extra features included.
When it was first displayed, people from disparate departments who didn't even turn up to any of the meetings started saying "But how are we supposed to put people who are remote to the client you've written, with no tech training and no time to learn how to access a command line command supposed to use it? We need this! It can't be used without this!".
So, back to the drawing board. The rework was from the ground up, and what was now being coded looked nothing like the original request. The scope of the project was way out of wack, and the timescales too.
The saddest part of this is that even after I'd explained to them (after completing the project) that the whole thing could have been done far faster and more efficiently if a Spec doc had been produced, next project to come round, they did exactly the same thing again.
Needless to say, I left in disgust, and stress, and am now at a place that understands the need for doing things properly.
A spec doc is rarely right "First time", which is why you need several people working on it, to bounce ideas around, and pick out holes. That way, you know what the product IS before you ever start the formal design methods.
If you don't know at this point what it looks like, you may just end up asking for tank tracks later..
Just my tuppence worth,