Fog Creek Software
Discussion Board

Whats a little requirement between friends

I recently had a disagreement with my boss on what requirements analysis and functional specification should document. I’d like to discuss my thoughts and situation and see if I’m not being too pedantic.

Personally I believe that a requirements analysis should state _exactly_ what the client would like the application to do.  If at any point the developer creating the functional specification is confused as to what goes where then the requirements doc isn’t complete.

For example, Big Boss Bill at Cuppa Joe’s wants a simple “form” developed that he can send to all his staff to find out exactly how they have their coffee.  They will fill in this form and send it back to be collated into a single repository which he can use to generate a report.  The following will deal with the “form”.

After talking with the Big B the requirements for the “form” include the following information. It needs to run on everyone’s PC without requiring the installation any 3rd party software, should gather the persons details (name, location, email) and their coffee particulars (coffee brand, quantity, sweetener type (brown sugar, white sugar, honey, sucrose, sweet n light), quantity, creation steps). You may have noticed that there’s a lot more information that could be added here, but we’ll leave it at that for the moment.

In basic terms this information will then placed in the requirements analysis document using number bullet points for each requirement which is then signed of by the Big B and the project manager/business analyst/you get the picture.

The functional spec will be developed from this document.  It will document how the requirements set out in the requirements analysis (identified in this document by the requirement number) will be implemented (what application are you using, what does the form look like, what fields are in the form, where are the fields placed, etc).

Now, using the previous example, the Dev’s just finished his functional spec with all requirements having been met and documented, had it signed off by his project manager, and created revision 1 of the application.  When the Big B sees revision 1 he asks why there isn’t anywhere to enter the fact that he adds a splash of full cream milk. Doh!

From here the requirements analysis gets modified to reflect this additional data. This again gets signed off, the Dev modifies his func spec and hey presto revision 2 of the “form” is born.

My view is that the requirements analysis is wrong. If it had correctly detailed that this piece of data needed to be gathered then the rest would have followed.

My boss’s point of view is that the requirements analysis document explains basic top level requirements. The Big B wants an input sheet for gathering information that needs to run on everyone’s PC without requiring the installation any 3rd party software, a database for storing information and crystal report for reporting on the collated data.

Information pertaining to what data is to be collected should be documented in the functional spec.

Am I totally insane?  Do I expect too much from a requirements analysis and too little from the functional spec?

Dazed and Confused.

Jack lives over there ->
Monday, July 1, 2002

Being fresh (relatively) out of university on this topic, I'd have to add that you are correct.  Requirements should detail "everything" including the "details" (the what).  Functional spec should be the high-level implementation details for the requirements (the how).

However, if you take it too literally then you spend alot of time writing documentation and very little implementation.  If the client is non-technical and/or this is something entirely new for them.  They don't know what to expect and you'll probably get only 50%-60% of the "detailed" parts of the requirements out of them (maybe even less, depending on the size and complexity of the details).

Your boss is essentially cutting that corner; he's skipping including the messy details in the requirements spec.  You know it's going to be incomplete or incorrect anyway, so delay the messy details until later. 

Since your building a desktop application with (most likely) a quick turnaround for changes and speed/ease of getting out prototypes I don't disagree with your boss. 

It's a trade off between documentation time and built/installation time.  If your building a huge application with a costly implementation you need to get as many requirements as possible (it's costly to do otherwise).  The smaller the application the more the scales tip the other way.

But then that's just my opinion...  ;)

Wayne Venables
Tuesday, July 2, 2002

Some people will say that there is no difference between a requirements document and a functional specification. It just depends on which part of the country you come from.

Inadequate requirement analysis is extremely common. You should appreciate your responsibilitiy as a spec writer to think critically about the requirements from Big B and question anything that you think might be wrong. You need not be a coffee expert to realize that some people might use cream.

The three most likely places you'll discover inadequate requirements analysis is when writing the spec, writing the code or during testing. It really doesn't matter what you think constitutes a requirements document within your enterprise. What matters is that the real requirements are discovered as early as possible, i.e. before the code is written. That away, you'll write the right thing the first time, on time and on budget and everyone will be happy.

Big B
Tuesday, July 2, 2002

Wayne, thanks for your input.

I understand what you're saying about trading off detail for certain projects and it's certainly true that a requirements doc will rarely (if ever?) achieve a 100% hit rate, but you can't blame the client for not being able to deliver the requirements to the dev's satisfaction.  I would think that this has a lot to do with the person asking the questions rather than the person producing the answers... there are no bad students only bad teachers?

I'm currently developing software for technical tasks which few people outside of the product line departments within my company have more than a basic understanding of (I have almost zero unstanding). It's not part of my role to know what they do in detail (there's way to much info for that), but it is part of my role to get the information I need from them. That's the biggest reason as to why the req analysis needs to be as detailed as possible. 

Still dazed...

Jack lives over there ->
Tuesday, July 2, 2002

This is one of my favourite bits.

When you say its not your job to know the details you're wrong.  Its exactly your job to know those details, respect the domain experts in that department and use them properly.

Don't interview them, people forget half what they really know when its a direct question.  Learn how to gather information without directly taking notes, have conversations.  The majority of absolute measurable information is usually in the forms, its the way those forms are used and misused that is important.

Don't underestimate the resistance of people to being told that some analyst is going to specify a system that they'll use.  They've probably been burned a number of times already.

Give them a true sense that they can be involved in the specification and use of this system, you really have to become their representative to management.

And finally never obfuscate or lie to them, if you don't know tell them.

Simon Lucy
Tuesday, July 2, 2002

> I would think that this has a lot to do with the person asking the questions rather than the person producing the answers... there are no bad students only bad teachers?

Well, up to a certain point you are right, I guess. If the customer is not asked precisely and is not informed about what kind of input is needed, there is no way she can provide proper requirements. But this asking the right questions is only part of the story. In many cases the customer really does not know what she wants from the start and, what's worse, does not want to spend too much time thinking about it. It is so much easier to wait for an output and then criticize it than to think beforehand.

Sometimes this is not a bad approach, either, as long as both sides know (and constantly keep in mind) that the first thing the programmer produces is a prototype, not the attempt on a finished product. And the second and maybe the third also and then we might go for the real thing.

If the customer wants the resulting software to act as she has it in mind, she has to spend time on communicating those thoughts to the developers, either right from the start or in intervals over a longer period of time. It requires work on the side of the customer. It is important to make that clear from the beginning. Asking for a specific software to be build is not like ordering a new washing machine from a catalogue. There is work involved on both sides. (This is true for external customers as well as internal, like the sales department or whoever is giving the requirements for a from-the-shelf product).

Of course I love precise specifications from day one. It's programmers paradise. But I can also live with the prototype approach, as long as I know that what I am producing right now is a prototype. What really drives me mad is when I (and the customer, too) think that I have all the input I need, build something I fall madly in love with, and then the customer tells me that this is not what she meant from the beginning.

Even though I know this problem and try to avoid it from the beginning in the projects I am involved in, it normally does not work. The main argument seems to be time: "We do not have time to do a prototype first, so head for the real thing straight away." Needless to say that it does not work, because we end up with a "real version" that is treated as a prototype anyway and we could have saved a lot of time planning it as such from the beginning.

Sorry, that was a rather longish post,

have fun,

Jutta Jordans
Tuesday, July 2, 2002

I loathe and detest prototypes.  They give the impression that stone pixies have chiseled the thing out, that the app is done and dusted since, hey it looks like it works.

Prototypes are millstones, leave them to grind corn not hang round your neck.

If you ask a carpenter to produce a bookcase (a very expensive bookcase), do you expect him to provide an almost working model?  Yes he may produce a sketch but that's what it is a sketch. 

Oh, someone might say, what about an architect and a shopping mall, surely they produce models.  And so they do, what bearing they have on the actual finished building is moot, they are largely selling vehicles, either to convince the money or to convince the poor schmucks who have to live with the real thing in the end.

If you use the right techniques, do what you need to do when you need to do it, then you can achieve the same thing by developing the app and presenting it as it goes along.  Because you are building the app you can change it as people's expectations and requirements change. 

All too often I've seen more effort put into revising prototypes than in actually producing a product.

Just say NO.

Simon Lucy
Tuesday, July 2, 2002

Are you seriously proposing that the only reason architects build models is to scam customers?

Matt Christensen
Tuesday, July 2, 2002

Where did I say scam?  I think its best to maintain some sense of humour.  I don't think anyone could justifiably point at some shopping mall and say 'its different to your model' or even that it was necessary to have a model to build a shopping mall.

I suppose I made those comparisons to partly point out that the building of software applications has nothing to do with physical engineering in any of the disciplines.

Simon Lucy
Tuesday, July 2, 2002

  Precise requirements are a myth for students. You just don't find them in the wild. This leaves you with two options: You can pretend that you have them, that the list of requirements the customer has given you are complete and exact. That you can trot off and build it and everyone will be happy. OR you can accept that the requirements can't be that, and instead gather requirements that are true and build from them.

  In the example given BigB wants a form to gather some basic information about the coffee which will run on pretty much any machine without hassle. I'd argue that's a pretty good requirement. You'd want a few limits, for example, you might say that he has just one page to gather this information - and if he asks for more later he's violated the agreed specs, and so forth.

  This isn't to say that it would be nice to have precise specs, simply that they aren't a real world thing and acting like they are will cause pain in your schedule, and your relationship with your customer.

  Prototypes are a good thing, just build them so they LOOK like prototypes so no-ones fooled. 

Mr Jack
Tuesday, July 2, 2002

Sorry, I kinda got into a "fault with requirements" discussion on another topic.

"Precise requirements", whatever that means, is just an illusion.  It assumes and places the burden on the customer slash user to tell you what they want.  It can be used as a means of deflecting the blame when you fail, and maybe you will buy it also... as long as you never recognize that most customers will sign off on anything placed before them... trusting you to do your job.

As development proceeds toward implementation, you will find out the customer doesn't know what they want.

Then you will start the next project under the same assumption, further assuming that to make it all right just needs more detail, more precise information, more volume of paper.  More work to find out what the customer wants which you have already proven doesn't exist.

An alternative is to use the "what the user wants" requirements as a symptom of a requirement, not as the requirement itself.  Then (*after a miracle occurs*), you provide what the user "needs", not what they said they wanted.  Then they will be able to tell you what they want - exactly what you gave them.

Joe AA.
Tuesday, July 2, 2002

On the topic of prototypes...

If the customer sees something (a screen) they will assume its working.  Show them a complete prototype (with no underlining code) and they'll think it's nearly done.

I never give my clients hollow prototypes.  Get enough information to build something then release early and often.  Get them something basic in their hands that they can use.  Maybe it's only 5% of the total project.  (and don't show the buttons for missing 95% -- add the options as the parts get complete).

Once the clients have something, they are MUCH more capable of giving requirements / explaining their needs.

Wayne Venables
Tuesday, July 2, 2002

Hmm... another offhanded thought I had... is what about "game developers"?  Certainly they want to provide something of value to their customers, but do they really ask their customers for "requirements"? 

I don't know, just asking.

Joe AA.
Tuesday, July 2, 2002

In a small company that I work for in the midwest (US), Requirements and Functional Specs are used interchangebly.  It is not of much consequence, however, since it seems that sometimes we prefer to have the illusion of development process, rather than process itself.

I would agree that precise requirements are an illusion, though I don't know how much of it is attributed to being lazy or not doing one's job.  Here, we work through several layers of indirection when gathering requirements :P,  e.g. Users of their product talking to their staff, who then talk to their managers, who then talk to their administrative sales contacts, who then talk to our sales contacts who then talk to our managers who then talk to us lowly developers.

It does seem however, that some sales people & managers are very good at getting at the meat of the requirement, or the "need" as a Joe AA put it.  Whether that *then a miracle occurs* step is purely luck on the part of those certain people, or possession of some kind of requirements divining rod, is beyond me.  But when it's right, it's no question that my job is a lot easier.

Tuesday, July 2, 2002

Ben Kovitz's book "Practical Software Requirements" gives the best description I've seen.

The computer is a machine that you can configure to have some effect on the outside world.

The requirements document describes the outside world (libraries; pizeo-electric speakers), and what the machine will do for the outside world (record book check-outs; drive the speaker at three frequencies---but not five).

The specification describes exactly how the machine will appear to the outside world as it does its work (the screens and forms for data entry; the +/-1.5V sine wave on a copper pair).

The design can then be anything that satisfies the spec---except that the real world may impose certain limitations (which will appear in the requirements document).

Tuesday, July 2, 2002

My solution has been to break the "details" out of the requirements.  For example: 
System will let users choose coffee options.

Note:  For next version, options offered will be "black, cream and sugar, milk no sugar."  Final list of options will be obtained by surveying staff and including the top 10 requests.

If someone wants to obsess over the details, I try to hand the job over to them.  I try to design the system so that these things are able to be changed quickly and easily.

Also, it can help to get a senior person on your side.  Explain that you can handle any emergencies or actual important changes, but that silly whiny wanking and nervous nellying will destroy the budget and deadline.  I got a senior VP to agree that any changes after a certain date had to be approved by him.  Amazing how the ego driven, procrastinating BS just faded away.

Contrary Mary
Tuesday, July 2, 2002

I think worrying about the particular coffee ingredients is part of the problem.  We know the boss wants to capture coffee making information but we may not know all of the data we will need to capture.  Iced coffee may become the rage next week for example.  The system should be made to allow for new items (I know this may be hard with a paper form). Instead of trying to nail down everything plan to add new choices. Then the reqirements become much simpler and the system becomes more robust.

John McQuilling
Wednesday, July 3, 2002

"Hmm... another offhanded thought I had... is what about 'game developers'?"

We 'pitch' a concept doc for the game. This has flashy artwork in that will in no way resemble the completed game but impresses publishers; as well as describing the game in broad strokes, with a few details we'll later change. After the publisher takes the game on, we develop a 'Design document' which will rapidly become inaccurate as the game progresses, and invariably contains a number of long-since dropeed ideas. The publisher agrees to everything in this document, and then changes their mind later without letting us make any change to the schedule. Generally these changes are spurred on by someone in marketting who has never played a game but has heard that 'Quake' is fun, and thinks we should incorporate a RailGun into our Olympics sports title, or by someone who has seen our functionality-complete but graphics-unfinished frontend and decided it needs a complete rethink because the graphics aren't very good.

"If I sound cynical, it's because I am."

Mr Jack
Wednesday, July 3, 2002

Prototypes would be so nice if only the client could be made to see that they are not the full product minus a few small details to be completed. Do you guys think it is helpfull to never show the client the actual prototype on a computer, but only screenshots of it printed out on paper after you have pulled them through Photoshop and applied those nice filters that make them look like handdrawn sketches? I know it sounds corny, and I haven't tried this myself, but it might just do the trick.

Just me (Sir to you)
Wednesday, July 3, 2002

*chokes on glass of water*

Mr Jack, you are a sick, bitter, and twisted person.

Your membership badge is in the post.

SB&T Club
Wednesday, July 3, 2002

Powerpoint is really good for prototypes like that. That way they get to see what the software will look like, and it's blatantly obvious that it's not done.

Chris Tavares
Wednesday, July 3, 2002

But it isn't.

I've seen CEO's and the like so impressed with Powerpoint and Flash prototypes that they take the functionality demonstrated as if it were done and dusted.

Writing the app seems relatively trivial to them.

If its worth expending all that energy to build a prototype build the damn app instead.

Simon Lucy
Thursday, July 4, 2002

*  Recent Topics

*  Fog Creek Home