Sanskrit, the secret of India's outsourcing success. 18

snip

That's a problem, for sure. It says you need a different approach. Read on.

They won't support it as such, but writing a good set of test cases should help you by highlighting parts of the spec that are vague, ambiguous, or just incomplete. Contradictory elements might evade you during this process.

Note: vagueness and ambiguity are different faults in specifications.

Vagueness is indicated by readers asking for things to be made more specific. Statements like "The new system shall be faster than the existing system" are vague. How much faster should it be? If you don't have an answer to this, you cannot test to see if you are fast enough.

Ambiguity is indicated by readers asking which of two or more possible meanings are meant. An example of an ambiguous statement is something like, "The new system shall perform better than the old one." What does "perform better" mean? Does it mean that it uses less memory, handle more requests per second, process each request quicker, etc.? You need to decide or find out which is-are correct.

That wasn't quite what I meant. I was thinking more of your statement "the spec is incomplete." This type of statement has occurred so many times in so many organisations that it's almost a clichˇ. "A posteriori" means arguing or developing an idea based on empirical considerations - that is, on evidence and experience.

Besides, "ten requirements" is a bit vague in itself. If the requirements are sufficiently "high-level", this could be all you need. It will lack *detail*, but it will specify at a high level what the system should do. All you need to do then is flesh out the details in the ten requirements. More often, ten "discovered" requirements will be an incomplete set, leaving gaps which are actually required but not stated.

As for designing it yourself and then getting the Indians to build it, bear in mind that you then have to deal with *two* kinds of specifications. The first is the requirements specification and its friends. This is the specification where the end-user (or the customer) tells you what is required. It is normally incomplete, vague, and ambiguous, and quite often contradictory. It is hard to refine, since you are normally dealing with people unused to the kind of pedantic rigour that is essential when writing code.

The second kind of specification is the one used by the designers and architects to convey the design to the programmers. In a single-site environment, especially one where the designers participate in the coding as well, this specification can be extremely informal, but as the two groups move apart, to different buildings, across town, a different state or county, a different time zone, or even a different continent, the need for more rigour grows stronger.

Sure, but people, especially programmers, are notoriously bad at reading documentation and following what it says. I recall a previous job I had where I built a framework for building a network application proxy, and presented to the teams that would be using it how I thought it should work, and which way it should be used. Not one of them used it that way, and all of them had problems with it as a result.

Yes, but it's still something you need to be aware of.

No, not all of them. Some changes are purely *semantic* in nature, and the compiler cannot see these. The typical semantic issue occurs when the interfaces prove not to have been as "pure" as everyone thought, and implementation details are "visible" through them. You know, "everyone knows that if you pbutt NULL here, the system accepts it and quietly does nothing, returning a success code." But of course it was never *specified* that this would be the behaviour when a NULL was pbutted, and, worse, maybe it was never *intended* that this would be the behaviour. A new module is created, and this module really cannot tolerate a NULL, and breaks the system by returning a failure code, or by crashing horribly. Whose fault is this? Well, actually, it's a specification failure. The behaviour when a NULL was pbutted should have been specified, and then the new module could have been written appropriately (or the calling module could have been coded not to expect this behaviour).

Ah, forward planning. If you're taking lessons from the XP approach, you should be wary of this. OK, you're building an application framework (of a sort, anyway), and the original white XP book specifically mentions that frameworks don't sit well with XP, but you can still take lessons from it. The XP books tell you that you should buttume that you almost never are able to make use of the forward planning, and it is therefore a waste of time. This isn't directly applicable to frameworks, as they must accommodate many different uses, but bear it in mind, anyway.

OK, so you have a requirements Debt Management problem. That's OK, everybody has to deal with this problem. There are many ways to address this kind of problem, including exploiting it to get a narrowly-focussed system, by delivering each small piece, one (or a small number of them) at a time. Make sure to have the system fully working (even if it's only part of the totality of what they want) at each stage. Make sure that at meeting N, the light-brown toast is the perfect shade of brown, at exactly the right temperature, delivered in a toast rack to stop it getting soggy. When you add waffle support, make sure that the waffles are done just right, and that the toast is still perfect. (Regression testing is your friend.)

I strongly advise you to get hold of (and read!) Rapid Development (by Steve McConnell, Microsoft Press, ISBN 1-55615-900-5). This is a great book, chock-full of ways to address all sorts of problems in developing software, including the incremental delivery method hinted at above.

-- SteveR

Humans are way too stupid to be dumb animals.