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.

The system shall...


These days, I've been writing software requirements for my new projects. There's a lot of:

a) The system shall provide (...)
b) The system shall allow the user to (...)
c) The system shall be able to (...)

Do you guys have the same problem? :-)
Just bored... Send private email
Saturday, April 09, 2005
Christopher Wells Send private email
Saturday, April 09, 2005
Yup, that's the way it is done.  That's actually the way it should be done, too.  I know it sounds redundant, but it's important to be able to separate the mandatory from the optional, and that's what "Shall" is supposed to do.

Now, there are additional weasel words which can bite you.  "Every" and "All" come to mind -- as in "The system shall handle all error conditions". 

They bite you because they leave undefined what ARE the error conditions, what are NOT error conditions, and WHO gets to decide what's an error anyway?

Worst case, this requirement requires your system to implement a fairly primitive form of mind reading -- both the user's and the customer's mind.  Not something I want to sign up for.

And they ARE like Mom and Apple Pie -- who wants a system that WON'T handle every error condition?  Just be careful what you sign-up for.  Personally, my systems don't handle hand-grenades, nor somebody pulling power, nor somebody hitting the reset button.  These are things the HUMAN part of the system needs to tell the operators not to do in normal operations.

And if my system really DOES have to handle imminent removal of power, there's ways to code that, but it can lower system throughput.  So you WANT your user to have to specify what he wants, so you can point out tradeoffs that he may have to make.

Somehow, it can't be all the developer's fault that these ballpark requirements are not met.  And oh, that's the other thing, no matter WHAT you implement some wiseguy can say it doesn't meet ALL the error conditions.  So it is quite likely you'll never meet this requirement, no matter how much rework you put in.
Saturday, April 09, 2005
The most important thing to do when you're collecting requirements for a system is to attach a few parameters to each and every requirement.

You need to know WHO submitted it, WHEN they submitted it, WHEN and WHO changed it along with the actual change.  And finally, you need to know the impact and priority of the individual requirements:

I measure priority from 1-10 with:
1 = do this last if there's time
10 = this was to be done yesterday

I measure impact from 1-10 with:
1 = the user might never notice if this works
10 = the project will be a failure if it doesn't do this

By getting these things early on, you can prioritize the requirements and determine where your effort should be.

And don't forget to reevaluate these on a regular basis because requirements WILL change, some will be added, some will no longer be applicable, and some will become more/less important as time goes on.
KC Send private email
Sunday, April 10, 2005
I have experienced two different angles on requirements. One is the list of what the software needs to do... "the system shall" approach.

The problem with 'the system shall' is that it doesn't lead to any sort of good organization or understanding. At best you have a list of stuff about the application. At worst, you get a contradicting, unorganized, unstructured mess that nobody wants to deal with:

39. The system shall make all links blue.
40. The system shall require that the user enter a billing address.
41. The system shall make links for expired records red.
42. Ignore step 40, instead, the system shall only require billing addresses for records that have a direct billing option set to true.

Disorganized and contradictory, especially when people start tacking requirements on to the tail end of what is already there. And usually, everyone in a position to refine it, based on business knowledge, gives up or passes the buck when it becomes too complicated.

The developer is forced to make sense of all of this and spends time trying to reverse engineer a solid functional design instead of developing code. And the developer is the least desirable person to do this because it is time consuming and requires close familiarity with the business reasons for the software. Developers definitely have the intelligence to do it, but the whole point of having someone other than the developer create the requirements is to divide labor most effectively.

The other approach to requirements is use cases. The use cases describe a story for the functionality in rigorous, narrative type language. There is a use case for each major functional goal in the system that captures the most common path to complete that goal, deviations from that course (possibly caused by errors), and tables describing any data that is involved. (explained much better in the book 'Writing Effective Use Cases' by Cockburn)

Designing through a set of use cases forces the project manager (or whoever is creating the requirements) to have a mental picture of exactly what they want before things go off to the developer. No more passing the buck or vague handwaving, and it gets away from the long unorganized list of 'the system shall' statements.

Use cases are a bit more difficult to write, but are much easier to discuss with developers and other stakeholders. When combined with mockups, they capture almost everything you need to know when developing the application. They are much easier to code against because everything is laid out in a stepwise fashion, so you code step by step without having to worry about missing something. And they are much easier to maintain because when you change one step, you can see what else you need to change so that the narrative makes sense again.
Russell Klophaus Send private email
Sunday, April 10, 2005
"The problem with 'the system shall' is that it doesn't lead to any sort of good organization or understanding."

I find that to be a strength of the 'shall' approach, not a weakness. The hardest part of writing good requirements is to write requirements rather than design.

Of the exeample "requirements" you listed I would consider 39, 41, and 42 to be design. Whenever I see a "requirement" that describes colors or flag settings I kick it back to the requirement writer and ask what them to specify the real need, rather than giving an example implementation of something that hasn't been specified. (Links need to have a visual clue that they are links? Okay, we'll let the designers and UI experts decide what that visual clue will be. But the requirement is that the links are recognizable as links, not that they are blue...)
Tom H
Sunday, April 10, 2005
My "problem" with "shall" is that you need to repeat a lot of stuff. Consider the following:

1)The system shall allow to the user to browse a list of orders.
2)The system shall allow the user to insert a new order.
3)The system shall allow the user to update an existing order.
4)The system shall allow the user to delete an existing order.

Maybe you just write:

1)The system shall allow the user to browse, insert, update or delete orders.

Then, you repeat this for all data entities you may have:

The system shall allow the user to browse, insert, update or delete <data>.

After writing this stuff like a thousand times for a thousand of projects, do you still do that for all your data entities? I mean, it seems that at certain point, people just skip this part and then focus on more important stuff.

How "complete" are your requirements?
Just bored... Send private email
Sunday, April 10, 2005
The first problem is that you the developer is writing requirments.

The BA along with the clients should be writing requirments, then the BA and system designer should be translating that into a system specification.

I think that requirments in general should better be frazed in terms of what an interaction should be.  ie. Before a user may use part of the system they must authenticate themselves

there should be further detail, and criteria that must be met to prove that the requirement is met by a system that is built.  ie.  The user must not need to remember or carry anything special to authenticate themselves.
To be fit for purpose people should be authenticated within 10 seconds.

Having a priority type info about the requirment is good, it should also include things such as if that bit breaks how important is it to fix and if something in that area changes how important it is to test it and the rest of the system.

We have a multi page template for defining a requirement, sometimes difficult to fill in, but all necessary to actualy garauntee delivery of the product.
gorf Send private email
Sunday, April 10, 2005
"The first problem is that you the developer is writing requirements."

So, if you work on a really small company and you do not have BAs, what is the best:

a)The developer may write requirements
b)Since there's no BAs, there's nobody to write requirements - just jump to the code-and-fix

My 0.02 cents.
A guy who works for a small company
Monday, April 11, 2005
Recognize there are no BAs, do some learning, change which hat your wearing and do the job of a BA, then change back to your usual hat and move onto defining the specs from the requirments.
gorf Send private email
Monday, April 11, 2005
I'm curious - what is the difference between WILL and SHALL?

Friday, April 15, 2005
The distinction is blurred in modern English. I remember being taught in primary school that the verb went "I will, you shall, he shall, we will, you shall, they shall". I've since realised that 'will' (related to 'would') deals with intention - hence the English terms 'willpower' and 'will and testament' - but 'shall' is related to 'should'. Since intentions don't come into it, it's more emphatic or more 'definite'.
Friday, April 22, 2005
That agrees with my understanding of "will" and "shall", with the extra comment that they are swapped for first person and second/third person:

"I will..." - signals a definite intent
"I shall..." - signals a likely action

"They will..." - signals a likely action
"They shall..." - telling them what to do

I think that Strunk & White gave this pair of examples:

The drowning man shouts, "I shall drown! No one will save me!" The suicide cries, "I will drown! No one shall save me!"

Hm... hope that's clear.
EKB Send private email
Saturday, April 23, 2005

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

Other recent topics Other recent topics
Powered by FogBugz