Benefits of the Specification

[Lexicon]

Working in Japan for the last year, I have come to know the importance of a good Specification. What can I say, I'm young, I hadn't programmed anything that really demanded one before. The Importance is especially relevant now that I've discovered the Japanese don't know how to produce one, but that's neither here nor there.

We all know the basic reasons for the Spec:

1. A Specifiation allows better Planning on the Programmer's part, which has about a bazillion ++'s of it's own.
2. Questions can be answered from the Spec instead of calling your Manager every hour with a question about how he wants something done.
3. A good Spec from the client allows proper time/money cost estimation and resource allocation.
4. It saves Time by causing fewer rewrites when things have to change (assuming you can stick to the Spec, which is Key).
5. etc...

However, I've discovered an important point which is at least as Compelling:

Attention Span

Programmers are well known to work better on interesting projects and the new and cutting edge. One can sit and consider the proper algorithms and data structures that are important to the project and let this get you through the inevitable drudgery of input verification and collecting data from your forms.

However, when (purely hypothetical example I swear) you've completely finished the project and most of testing and your employer decides it suddenly needs to be compatible with Netscape as well and now you have to rewrite not only the browser interface but also how the underlying document structure is formed but not so much how anything actually works, it reduces to being purely tedious.

All but the most diligent programmer will then end up rushing it or slacking off (by posting to Perlmonks for instance), which is inevitably bad for your final product. What a difference a simple decision can make. ;)

Anyone else have any not-so-obvious benefits from getting that Specification correct the first time (or at least entertaining anecdotes when it wasn't)? I could list a bunch of names of Monks who know better than I, but I wouldn't use a cheap trick like that. ;)

-Lexicon

[Malkavian]

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.".

An analogy:
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,

Malk.

[lachoy]

Specifications are good, yes. But I disagree that they can (or should) never be changed. Customers typically don't know everything developers or technology can accomplish that they can exactly describe what they want, and developers rarely know enough of a customer's business process to explain how the final product will look and act. (There is plenty of ego on both sides that screw things up: customers think they know what the best technology to use is and developers think they can re-engineer a customer's business process.)

Both are (IMO) best served by a process marked by short iteration periods and involvement by all parties (customers, developers and mangers) at all stages. As tilly pointed out this is one of the fundamental tenets of XP. I'm only about halfway through the recent book Planning Extreme Programming, but it's done a good job so far of pointing out trouble areas and describing the discipline necessary on everyone's part to make an iterative process work.

The projects I've been involved with where we tried to figure out everything necessary for the entire project at the beginning never did well because nobody (including me) appreciated the power of change.

Chris

M-x auto-bs-mode

[tilly]

Book recommend. Rapid Development by Steve McConnell. Actually I can heartily recommend everything that I have ever read that he wrote, but that book addresses the topic at hand. Including why a spec is nice, what a good spec should be, why you are unlikely to get one, what can (sometimes) be done about that, etc. A lot of this may sound like management theory. But it is really addressed as management theory for a technical lead (a role you can find yourself being thrown in unexpectedly - or be in by default by virtue of being the only developer) who would rather be a programmer but needs to know what works out of self-defence.

Another approach to the issue of the fact you will never get a spec is to try some of the ideas from extreme programming out. If you search you will also find some previous discussions of that.

[mirod]

Yes it is great to get a specification. My first sold project ever was in the early 80's, a software to teach music to kids, that evolved from what we (the programmers) had understood as half a dozen independent exercices that we could easily code in 2 month to a 4 month nightmare resulting in a complete music school management program, tracking kids results, offering appropriate exercices for their level... all that on a Apple II with no hard disk drive!

No you will _never_ work with a perfect specification. And in any case you will never be allowed to stick to it until the end of the project. There is always a good reason to change a spec. I once worked for a Space Agency, from which you'd expect Top Quality, Strict Processes and the likes, and as I was leaving, I was discussing with one of their long time programmers and complaining that I never had a good spec, and he aksed me "A spec? I never had a spec in 20 years here!"...

The solution? There is no perfect solution, we live in an in an imperfect world after all. I found that writing a spec is necessary, but then prototyping, showing results early and getting feedback from the users (_all_ the users, not just the guy who will pay for the project) is the best way to catch problems with the spec early.

[dws]

Specifications can have a way of taking on a life of their own, chewing up resources both to write and argue about them, and to keep them updated. Finding the right balance can be tricky, particularly when there are non-designing, non-coding "process" people in the mix.

I've found that it helps to clearly distinguish two types of specifications:

External specifications talk about externally visible aspects of the system. These specs serve as an interface between the development team and other stakeholders, such as documentation and QA. Getting these as close to right as possible on a large project is important. The trick is to put as little effort into getting them there as you can, since the process can a time vampire.

The type of external specification that I've gotten the most mileage out of over the past few projects has been Use Cases that describe concrete interactions between a user and the system. Uses Cases give the customer an early chance to say "yeah, that's how it's supposed to work" or "no, that's not the way we do things." And once the customer has signed off, they're a good customer proxy to have when a customer isn't available to talk with.

One thing I've seen projects skip doing when writing external specifications, to their eventual dismay, is to include a list of what the product won't do. A negative specification is a good way to keep Sales and Marketing in check! And you avoid some messy battles of the "you said you were going to do X!", "no I didn't!" type.

Internal specifications talk about what goes on under the hood. The conundrum here is that while most people say they need more in the way of internal specifications, most of what's produced (in my experience) has a short shelf-life, and little long-term value. The lasting internal non-code artifacts are typically diagrams: A one- or two-page object model, an interaction diagram, a decorated database schema. Other documents, unless they're close to the code, tend to drift off towards the bottom shelf or the back of some desk drawer. So, draw pictures.

Since the final authority is always code, keeping internal specs as close to code as possible can be a win. A lot of Perl code gets this right by using POD, which is easy to extract it into HTML for on-line specifications. Judicious use of javadoc is a win if you're working there. On my current project, we write PODs and javadoc as part of the design process.

[PsychoSpunk]

I know firsthand that the most important aspect of a specification is signoff. The spec that doesn't have signoff by all involved parties (customer, programmer, and managers in between) will cause arguments. The spec that does have signoff will cause arguments, but these arguments can be solved by stating "Aha, here it is in the Spec."

But this isn't to suggest that the Spec is written and then placed under lexan glass in a humidity controlled environment for all tourists to come and be awed by. Until the deliverable is produced in final form, the Spec is a living document. Getting to that final form can be a pain with some Specs. I have one Spec come to mind where I produced code (part of which some monks gave me some really cool ideas for) that met every part of the Spec. The problem was that the client kept getting error messages (that were part of the Spec if an appropriate string wasn't entered). In review, my code met every requirement of the Spec, but the client had not met their end of the bargain. Guess who wins that situation?

So, I changed the program's code so that the client would not have to ensure that they had all of the data in their database built properly. The entered string still had to be verified, but it shows that signoff on a Spec doesn't mean that the client knows what they want (and this was a very detailed technical spec). I know that I've heard that somewhere before, maybe college. :)

Lexicon I don't think anybody gets the Spec right the first time, because the first time means that you have an idea. And no matter how well-formed that idea is, it's still not a set of electrons being beamed at your eyeballs in a concrete form you can interact with.

ALL HAIL BRAK!!!

[LD2]

Lexicon, I can't agree more. One of the places I worked for was a company that made their money off of their information and software. Their IT and Product Development had specs and testing for everything. I really hadn't realized the complete advantage to the programmer and to everyone else involved until much later. One's whole design is based off of it, but until it's agreed with one's manager and client on how and what the program should do.. one doesn't start it (which makes life a whole lot easier). Just a few months ago, I had a task to create a small program to do a very simple task - the feel and look of it was totally up to me. Well, there was no spec for it. I HIGHLY regretted it a couple of weeks later. The complete project was re-vamped from the bottom up - what it was supposed to do, how it was doing it, what it looked like.. The sad thing is the client didn't see it until it was approved by mgt (unfortunately, they wanted functionality of the first version.. but alas.. I have to leave it up to mgt as to when it will be revised again). I couldn't go back to the spec and say .. "See, this was the objective of the project.." - because there wasn't a spec to go back to. Everything was loose translation. I've learned my lesson well from that experience. I think no spec not only drives programmers crazy, but also the mgt... as well as losing time, money, and energy on projects. So, now I'm a definate disciple of.. Specifications.. ALWAYS!

[redmist]

The really Bad Thing about not thinking about the application, is that every time you add something, something else will inevitably break. It's like those squishy tubes that you sqeeze and they fly out of your hand...an endless process of adding in kludges.

h0mee and I were driving around one night discussing breakage, and came to the conclusion that It's All About The Data. Knowing your data will be the difference between breakage, non-breakage; a maintenence nightmare, and a maintenence pleasure. For example, in Programming Pearls, in the first column, Bentley (the author) discusses an old school problem of sorting thousands of 1-800 numbers using about a megabyte of memory. They ran into some Really Bad time-space issues with certain algorithms, so they used a bitmap vector to map the data. It was a novel solution because it was engineered to the data. The problem is maintaning a symbiotic relationship between data and algorithm whilst preventing breakage. Verily, this is very difficult.

redmist
Silicon Cowboy

[dws]

The really Bad Thing about not thinking about the application, is that every time you add something, something else will inevitably break.

Until recently, this has been predominant view: If you don't Plan Ahead, things will break later.

Extreme Programming offers a novel counter proposal: If you only think one step ahead, and at the end of each step you have a well-tested, well-factored system, then the chances of your breaking something on the next, not-yet-thought-of step are reduced to near zero. Well-factored implies good structure, with things done "once and only once". Then means that many decisions are well localized. A well localized decision is much easier to safely change or replace than once that's becomes spread out over time.

[redmist]

The XP point of view sounds good too, but I don't think that the two philosophies are oppposed to each other. It sounds to me that they both emphasize planning and thinking about the project before something is implemented, and one way that XP differs is that XP will plan in smaller chunks. Correct me if I am wrong.

redmist
Silicon Cowboy
UPDATE Thanks for the clarification dws.

[Lexicon]

I did make a pretty strong point about Sticking to the Spec up there, perhaps over stressing that point. Obviously the spec can't think of everything, or it would have already developed the whole application. But non-trivial rewrite 50% of the code changes? I'm just not down with that. This is even more complicatd by the fact that another developer wrote about half his client side in vbscript and then quit. I'm more entertained than irritated, but it still gives me a headache.

lachoy mentions a problem of client ego thinking they know what's best. In my experience here (but I'm saving the brunt of this rant for later) that the client really just wants something wiz-bang and wants you to PSI::ESI exactly what that is out of them. Development cycles in Japan flip back and forth on the order of hours or days at most (at least at my company).

The developer runs into a problem (frequently), management can answer it about 1/2 the time and otherwise calls the client. Sometimes management will save up a bunch of questions and take them to a meeting to get it all out. Meetings with clients are every week or so. I have more to say, but I'll save it for another post towards June when I've completed my year here and I can be as complete as possible.

-Lexicon