Re: Benefits of the Specification
by Malkavian (Friar) on Mar 08, 2001 at 16:30 UTC
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,
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
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
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.
Re (tilly) 1: Benefits of the Specification
by tilly (Archbishop) on Mar 08, 2001 at 17:20 UTC
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
Another approach to the issue of the fact you will never
get a spec is to try some of the ideas from
out. If you search you will also find some previous
discussions of that.
Re: Benefits of the Specification
by mirod (Canon) on Mar 08, 2001 at 15:08 UTC
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
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
Re: Benefits of the Specification
by dws (Chancellor) on Mar 08, 2001 at 22:20 UTC
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.
Re: Benefits of the Specification
by PsychoSpunk (Hermit) on Mar 08, 2001 at 22:48 UTC
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!!!
Re: Benefits of the Specification
by LD2 (Curate) on Mar 08, 2001 at 21:31 UTC
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) Re: Benefits of the Specification
by redmist (Deacon) on Mar 08, 2001 at 23:46 UTC
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.
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.
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.
UPDATE Thanks for the clarification dws.
Re: Benefits of the Specification
by Lexicon (Chaplain) on Mar 09, 2001 at 05:50 UTC
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.