The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.


This is a spinoff on a previous topic in this forum "should I become a project manager or a business analyst?"

It made me start to think about requirements. I realize that the level of formality in requirements is related to the size of the project. In other words, a programmer that develops a tool for his own use may only need to sketch requirements on a napkin, if at all. On the other hand, a large business project with many developers SHOULD have requirements specified in some sort of document.

I have been suprised at the number of developers that I talk to lately that tell me that the requirements work that they recieve is poorly done. This often leads to requirements churning later in the project.

What has your experience been?

Who writes the requirements for your organization? Project Manager, Business Analyst, Developer?

What tools are being used to develop requirements? Word, Visio, Powerpoint, prototype in code, Rational Rose?
Roger Jack Send private email
Monday, December 20, 2004
Hard to generalise, but I've observed that the projects that "fail" (over time / over budget etc) are those that have used an modelling toolset that is over-complex for the project.

Use the simplest modelling toolset to start with, and then get more complex if you have a valid business reason to do so. is a good resource.
Marcus Price Send private email
Monday, December 20, 2004
I've worked at both ends of the spectrum.

Sample 1: Bank. Requirements for a simple web page were about 50 pages long. Took longer for the PM to write them than it took to do the actually coding. I know they were CMM-3, but I think they were shooting for CMM-5. Some of the dead tree collection was to satisfy bank examiners.

Sample 2: Insultant company (it was the IT dept for some consultants that did just what the consultants did in Office Space). Project started with 2 drawings and 1 excel mockup of the interface. Original estimate: 4 man months. Final bill: 40 man months. Since the "client" VP used the porno standard of programming ( = I'll know it when I see it), the goals moved every single week. BLUE! BLUE! What sort of idiot writes a doohickey in BLUE? Or, in more domestic terms, I think the couch would look better over there. No, I think it would look better back where it was. No...

Current place: requirements are written in Word. Maybe a Visio drawing or 2. If there are NASD or SEC regulations involved, I use a spreadsheet to check off which pages/modules are affected, and if a reg changes, what code needs to be revisited. Maybe I will make my own little app/add-in for keeping track of this stuff, but for now, excel files are fine.

Whatever works is good enough. If you can understand what the customer wants, you win. Of course, if your customer doesn't know what they want, then it is like arguing with your wife: no matter how right you are, you are still sleeping on the couch.
Monday, December 20, 2004
On the last project I worked on, the client gave very detailed requirements, which were good for the most part. However, they tended to duplicate logic in different documents. For example, we're not supposed to show a certain widget under certain conditions. Since that widget appears on several pages, they would write out the same set of conditions on the requirements for each page. Then, when those conditions changed, it was hard to remember to change all the relevant pages.

If I were doing it again, I would encourage them to consolidate logic like this into one place. It makes everybody's life easier.

Also, get them to give broad requirements for look-and-feel, such as "headings are 14-point bold arial" rather than specifying each element individually. On all the projects I've worked on, the client started out giving intricate details about fonts/sizes/etc. But by the end, they would just say "do it like the rest of the pages." So it helps to have some generalizations in the requirements.

Also, make sure there is a process in place (doesn't matter what it is, as long as it's well-defined and you use it) for having them submit changees to the requirements.
Monday, December 20, 2004
"I have been suprised at the number of developers that I talk to lately that tell me that the requirements work that they recieve is poorly done."

I'm surprised at that statement as I've never seen a complete and thorough set of requirements handed to me.  Most of what I've seen is written at the 20,000 foot level (at best) and never gets to the ground level of actually specifying system behaviours and such.  It is not uncommon for me to read one paragraph of a typical requirements doc and formulate 20 questions that the paragraph begs but does not answer.

Maybe I'm working at all the wrong places.  :-/
Monday, December 20, 2004
You original question seems to be in multiple parts, so I will try to answer them in order.

1) Requirements specification is normally something that should be done at the senior developer/architect level.  These requirements are derived through conversations with the customer or analysis of the client's requests.  These requirements are fairly high level and will generally specify the overall behaviour and architecture of the project.

From this point, you can broaden the spectrum to look at the derived requirements this will introduce to the system.

2) Once captured, the requirements need to be stored in a single place.  Ideally, a tool such as DOORs would be used to store the requirements and provide you with all of the required linkages but this data could also be stored on a set of recipe cards.

That said, the problems of managing requirements is trivial in comparison to finding people who understand how to write requirements.  While many people can say 'it needs to do x', they often forget to tell you why they think it needs to do this.  Often, you will find that what they mean is that 'it needs to do y, which always happens if you do x'.  It takes a particular type of person to be able to drill down and find the actual requirements instead of just the popular perception of requirements.
Monday, December 20, 2004
I have worked with both good and bad.  Neither was perfect but my last shop was better than now.

Last shop had the business owners at a high level create a complete system overview plan of how they wanted it to work as a whole.  This was then redone at a more departmentalized level with more detail.  This process continued till you got down to the nuts and bolts of the individual functionality.  These were all word documents with tables in them for all the cross-referencing.  The nice thing was the general look and feel was in the higher documents and only the real small parts were in the detailed specifications.  The problem being you have to go to the top level and work your way down threw all the “Linked” documents to make sure you had the complete set of requirements and from there the programs effected.

My current consultant job just sends an e-mail saying process A is doing X and "that’s wrong" make it do Y.  If you’re lucky they might give you an example of how and where to make it produce X.  I spend a lot of time getting more details about process A and exactly what behavior Y is and if its even legal.

To answer the question of whom should do the requirements.  To me several different people need to be involved for a large project.  You need the end users to give the general look/fell and big picture.  Then someone probable a business analyst needs to take that big picture and drill each piece down to the individual business rules that need to be applied, included where and how to apply them.  From there a system architect would look at the technologies available as well as what systems are al ready in place to get the technical approach made.  If you are a shop full of ‘Small Brain’ programmers or code monkeys you will need someone to make individual specifications for every piece.  Or if you have developers who are used to taking the specs and producing their own technical design, documenting it and then coding it you can then turn it over to them.
Douglas Send private email
Monday, December 20, 2004
Requirements are interesting.  In most cases they help resolve ambiguities and help to quickly identify who is accountable when a dispute over functionality arises.  In the worst case Marketing writes requirements and they produce many words but little clarity.  Always have one programmer involved, someone who is going to grasp technical issues and can help limit scope.  Another thing is spec changes.  I worked on one project where the Team Lead tracked the SRS volatility, this was in a rigid environment (product needed FDA approval), he did a great job of showing the impact of spec changes and was able to use his volatility chart as ammunition when ideas about design changes would start to circulate, this meant that the team wasn't interrupted with constant additions or changes.  Converse to that example, I worked in an environment where we were hostage to the whim of the owner, our requirements process involved a Flash developer (? are they called developers) who would go into the owner's office, listen for an hour and nod his head "yes" anytime the owner asked if he was following.  Needless to say that this guy would walk back to the dev team and start recite a mish-mash of what he could understand and didn't understand, punctuated with statements like, "You're going to love this" and "Check this out, it's not even possible" (to which I always said why didn't you speak up then?).  Obviously that is not requirements, but my boss claimed it was adequate, eventually my insistence that I be allowed into the meetings helped.

I like the idea of a two stage breakdown, the first being a "business level" requirement specification, and from there a "software level" requirement specification.  At the business level are the Domain experts, the "Analyst", an "Architect", project manager and a dev (always have one dev), it's reasonable to expect that the dev and PM aren't big contributors here.  Take your architect, PM and dev then outline the software spec.  Centralize the documents and develop a cross referencing scheme that works without being overly complicated.

One technique that I've seen used on different projects with varying success is the "GUI Mock-up" spec.  This tends to be good for the "know it when I see it scenario".  In the days of perverse Web application spending (read pre 2000) many companies would use the mock-up as a tool to actually sell the client.  So after an initial investment in pretty pictures it made sense to chop those out into their component parts and explain what each piece should do.  This technique is strong in that it can get right down to the details of a widget pretty quickly but weak in that it often misses many of the business "rules" and business level requirements, this is usually a case where marketing sells something to client using a picture and many assumptions are made (not communicated, never pressume you are on the same page as the person sitting across from you) the client expects things to work a certain way and the marketing/sales team is just trying to the give the client the warm wet fuzzy in order to seal the deal and tends not to really grasp the client's need (this is why an Analyst should be involved with the sales process, and a dev).

People who don't believe in requirements are:

A) Working in their basement on projects which will never leave their basement.

B) Loosing money and time and providing unsatisfactory results to their customers.

C) Mis-informed.

People who believe in requirements but don't always have a good implementation:

A) Are probably sitting next to you.

B) Have jobs and work for a living.

C) Willing to try a new implementation because they know what it's like to get burned by the "this isn't what I asked for!" syndrome.

D) Read postings about opinions on requirements.

Requirements are good, smaller projects may get away without them, for my product we've attempted to establish some but they are mostly hand written notes.
Verbose as always.
Jay Lauffer Send private email
Monday, December 20, 2004
I think the point is that requirements add cost, and they provide significant benefits.  Just like anything else, you need to do a cost/benefit analysis.  On very small projects, the cost of doing a long, formal, requirements document may outweigh the benefits involved.  What many people are learning now is the benefit side of the equation is much larger than previously beleived.
Joel Coehoorn
Tuesday, December 21, 2004
> I'm surprised at that statement as I've never seen
> a complete and thorough set of requirements handed to me.

I have actually. The problems were:
* it took 6 months to generate so we weren't going to make our release window.
* it was very long. Oh my god was it long.
* it wasn't done with development and included so many implementation level details that were just wrong that it invalidated the requirements. The requirements makers usually can't stop themselves from helping the poor stupid developers .
* as the developers didn't work on the requirements all the context that built up the requirements have to be recovered by endless discussions with the requirements makers wherein the requirements are rewritten. This takes another large chunk of time.
* the requirements makers think the requirements are the actual system and that they done the hard part. They don't see the utter complexity it takes to implement a lot of requirements.
* the requirements makers rule the developers yet have no real responsibility for the system.
son of parnas
Tuesday, December 21, 2004
Thinking back to the last few projects:

- Small, mini-requirements documents for each major feature set worked pretty well.  The key is to make it readable (so generally less than 5 pages with pictures, lists, and tables), and in English (or whatever the stakeholder's language is)

- Large, all-in-one, "complete" requirements are self-defeating, since by the time it is verified as complete and correct, the business has changed, meaning new requirements and changes to existing requirements.  Only a very stable business that never changes can do this

In general, I think small projects still need requirements, even if they're not complete.  It gives some sort of vision of what the thing is supposed to do.  I guess you'd call it iterative analysis - write down what you know the thing has to do, and keep revising as you build the system and learn more from the users.

It has saved me many hours of rework to commit ideas to paper (or whiteboard or napkin) and discuss with customers.  I don't think you can expect most customer to give you all of the requirements up front, so do a little requirements gathering and writing, make a little prototype, get some feedback, and continue.
Tuesday, December 21, 2004
Requirements flow down from the top level system concept.  The pervasive method is to create use cases at the top level.  These flow to system design, then these system level requirements, functional and non-functional, flow to software and data requirements.  As you might guess this is a perilous undertaking frought with mistakes.  And this happens no matter how good your team is.  This is why prototyping has become popular to let all the stakeholders get an idea of what the system will look and act like so they can speak up about requirements that are either missing or not needed.  It is also a way to test the non-functional requirements to reduce risk concerning things like COTS products that were supposed to perform as advertised, but failed to live up.  After all, if a project is going to fail, we would like to know as early as possible so we don't needlessely spend lots of money.
John Jenkins Send private email
Thursday, December 23, 2004
The thing with requirements is two fold:
  1. They're (very) dynamic: when they change frequently, no matter how many resources you pour into the 'Writing Requirements' task, your framed; QA guys, Technical Writers, developers, etc., all will read now and then a spec that is out of date;

  2. They're hard to read: either because the customer does not know them very well, or because he does not want to spend any time at all reading and aproving them (or is affraid of such an approaval).

There's not yet a culture of writing requirements (or functional spec) in a precise and easy to read way.
José Bonnet Send private email
Tuesday, December 28, 2004
Sorry, just forgot to mention MartinFowler's nice article on New Methodologies:

José Bonnet Send private email
Wednesday, December 29, 2004

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz