Clear Requirements

This may not be the place to define ClearRequirements, but any ideas on the subject would help the whole world.

A clear requirement is the holy grail of PerfectCommunication?: it may not exist, but that shouldn't stop us from looking. If the user or customer could communicate perfectly to the developer, there's a better than average chance that they would get what they require (maybe not when they require it, or for the price they'd like to pay, and maybe not what they really needed, but those are different stories).

An apparent benefit of UserStories over 'good' old-fashioned, more or less clear requirements is that no-one expects UserStories to be the complete answer, even if they are more than just SomethingToThinkAbout.

Placing a big bet

For purposes of planning and budgeting, managers typically want ClearRequirements written down before making the investment of writing a whole lot of code. For this purpose, the requirements need only be clear enough to keep estimates of time and cost within an acceptable level of uncertainty.

For example, if you are manufacturing a new microprocessor-controlled water pump, you will need to order parts for delivery by a certain date. There is a big lag between placing the order and receiving the parts. You'll want to be damn sure that the software is completed by that date, or you'll be sitting around with water-pumps that you can't sell. Since these water pumps will be used to cool a fusion reactor, you'll also want to be damn sure that the software was written to work exactly right with the hardware - even though the hardware is not available at the beginning of the project. You may well decide that you place a safer bet by spending more to document ClearRequirements in an early phase than by waiting until the water pumps are done and then having the programmers put something together. Or not, depending on the complexity of the software.

Of course, when you think things through in advance, there is also a risk that you might overlook something or spend lots of time on things that don't much matter.

KentBeck and the boys have suggested that with business software, and perhaps many other kinds, you can actually lower your risk by not thinking everything through up front. If you can get ReturnOnInvestment very early, with partial software, you can greatly reduce the risk of faulty requirements by gathering the requirements piecemeal, concurrently with coding. Often you don't need to place a big bet. Sometimes you can place a series of small bets instead.

Concur. Way too many of my embedded projects have gone this way. This is really a mess when the hardware vendor promises a certain level of performance from a part or a package and then you find out - too late, of course - that their claims are ridiculous. I had one client a few years ago doing an industrial thermal transfer printer that had so many problems of this type that it was physically impossible for the stoopid thing to come close to the specifications. Oy. Trying to convince them of this was a problem, so I had to rig up a bunch of tests for the electromechanical and CPU subsystems. What a pile. The project died a horrid death.

Too bad they never had clear requirements for the performance of this printer. There was one spec I tried to convince them they needed to think about that they never even gave a thought to. This had to do with the requirement that the printer keep up with the speed of the substrate (food packaging film, like potato chip bags) during the normal processing of the substrate in the overall system. Because of certain technical restrictions the printer had to be placed in a part of the machine where the substrate could be going through rather violent changes in speed at the time that the printer was supposed to be laying down the image. I did some acceleration/deceleration tests to show that the ribbon positioning mechanism not only couldn't keep up with the substrate, but even if it could the ribbon would eventually be stretched and torn. The client never figured out they needed a clear requirement on accel/decel. Too bad. -- MartySchrader

If the user or customer could communicate perfectly to the developer ...

I think this highlights my concern, i.e., the shifting of responsibility from the developers to the customers. Developers need to understand what is needed by the customer, not sit around and wait for a perfectly crafted document to be thrown over the wall (and subsequently ignored). Reality cannot be reduced to clear requirements; true knowledge and understanding is required.

Yeah, we all know this. The discussion is shaping up on PutaNumberOnIt/DontPutaNumberOnIt. Hopefully, we can arrive at some consensus that will eventually be refactored down to one page containing all the relevant observations.

The biggest thing here is to keep on communicating about the project. Everything is a process of change, where you just happen to start by changing a blank project. Keep your client informed, and keep her responsible. Start by making everything possible, even if it takes special skills. Move on to simplifying the common cases, as identified through your communication. Soon, your client will only rarely want some new feature. Eventually, the weird stuff will no longer outweigh the cost to automate. Furthermore, your client may decide to change his plans in such a way that saves everyone time and money. Your system will thus be perfect in every respect, tailored to the client, now and forever. Assuming it works, that is.

You know, there has been a ton of discussion along these lines here, but I still can't agree with the conclusion that just continuous talking with the client will solve the real communications issues. We have also discussed the need to establish a glossary of terms, etc. All this fades to insignificance when you face the condition I outlined above; that is, a client who simply doesn't appreciate the need to meet a certain requirement that their product obviously needs to meet. If you can't get an agreement on that then you are wasting your breath on any more talk. -- MartySchrader

Have you considered that the client may actually know what his needs are? Also, consider that if the unmet requirement is truly necessary, that it will come to light eventually. There is little advantage to delay work on known items in order to resolve issues concerning debatable items.

I am perfectly willing to concede that the customer may know a ton more about his product domain than I could ever hope to learn. What I am talking about is a simple (well, maybe not simple, but still) analysis of the underlying structure and support of the higher-level application. If the underpinnings can't perform to the needs of the given application even under ideal conditions, there is an obvious problem. If the client can't be made to understand this, then you have to bail. You can't make a silk purse from a sow's ear, no matter how much you talk about it.

Yet Another Example in a long history of this type: a client who makes valves for soda pop and beer dispensing machines was trying to create a new CPU-controlled soda pop valve. These valves mix the carbonated water and drink syrup at the time of dispensing. The valve measured the flow of both syrup and water and knew the proper ratio to achieve the correct "brix" value for a good drink. Both liquids were supplied under pressure, but the water pressure could be as high as 120 PSI. The valves were positive position, actuated with stepper motors. The electronics were adequate to drive the steppers at the maximum step rate and at more than sufficient current. The CPU had spare cycles. All cool.

Now we come to the valves.

The stupid water valve was completely incapable of holding back 120 PSI of water, so the dumb thing would leak like a sieve. The immediate effect was that the valve would dribble cold water on the hand of the user when the cup was withdrawn from underneath the valve. The client had tried every which way to make the valve stop leaking water on to the user's hand, but no soap. You should have seen the way they added valve closing code to overdrive the stepper in the closed direction, trying to shut the dribble of water off. Couldn't fix it.

My partner and I set up some tests to prove that the electromechanical valve assembly simply could not keep the water out from a 120 PSI intake line. It's hard to believe, but the client wasn't willing to throw a five dollar line pressure regulator in front of a $200 valve to prevent what became a product-killing flaw from reaching critical mass.

When you are faced with this kind of dumb-assedness on the part of the client then you need to make the painful decision to dump 'em and look for more work. There is really no other way to handle a situation that deteriorates to this level. Oh, well.

[Follow-up: a few years later, and my old (and future) partner told me he'd actually seen some of these CPU-controlled valves in place in Hardee's or some such fast food joints. The phunny? Every time he filled a drink cup the machine would piddle cold water on his hand when he withdrew the cup. They never fixed it, but put the dumbass thing into production anyway. Hah, hah, hah! -- MartySchrader]

I think that some of this discussion is conflating clear to mean both 'precise' and 'full'. Having requirements that are neither is a common problem, but XP seems to aim at addressing the 'full' issue by saying you need only work on the ones you know, and when new ones arrive, you can work on them; a well-factored project should be able to absorb the changes.

That said, having imprecise requirements will kill a project. I'm just coming out of a stint that had one, and we're still trying to get a solid definition to figure out where we need to change the code. -- PeteHardie

See: PutaNumberOnIt

CategoryRequirements