Requirements documentation
-
Jason McBurney wrote:
Have you ever read a "Requirement" document, and felt less that satified.
Definitely. I've written them too. It's very hard to say what makes a good req. doc., because it depends on the nature of the work. Some general guidelines are that a req. doc. should start with a general overview of the top level requirements. Each of those should drill down into sub-requirements, and this process should continue until all the requirements are sufficiently documented or you get to a point where you have to say "to be completed during design/development". That's actually a really good indicator for time and cost overruns. A req. doc. should also provide a storyboard of how the application interacts with the user, including screen mockups, flow diagrams, and screen state. It's usually very helpful to repeat the text with pictures. So, for example, if the requirement document says "when no row is selected the Delete and Update buttons should be grayed out" then it should also accompany this with a picture(s) and state diagrams that clearly define the requirements for button state. Nobody does detailed req. docs though, just as they don't do detail design docs or acceptance test procedures either. BTW, an ATP is the other side of the coin of a requirements doc. EVERY requirement should have an ATP line item to test whether the requirement is met. Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh SmithMarc Clifton wrote:
A req. doc. should also provide a storyboard of how the application interacts with the user, including screen mockups, flow diagrams, and screen state. It's usually very helpful to repeat the text with pictures. So, for example, if the requirement document says "when no row is selected the Delete and Update buttons should be grayed out" then it should also accompany this with a picture(s) and state diagrams that clearly define the requirements for button state.
Humm, What I am reading is ... People don't actually read requirement documents; therefore, the author must repeat himself many times? It is no wonder that nobody does detailed req. docs - The mangement folks, think these things are a waste of time... if we say the same thing in 4 ways ... they may have a point: How do requirement docs waste time?
You can only be young once. But you can always be immature. - Dave Barry
-
Jason McBurney wrote:
Have you ever read a "Requirement" document, and felt less that satified.
Definitely. I've written them too. It's very hard to say what makes a good req. doc., because it depends on the nature of the work. Some general guidelines are that a req. doc. should start with a general overview of the top level requirements. Each of those should drill down into sub-requirements, and this process should continue until all the requirements are sufficiently documented or you get to a point where you have to say "to be completed during design/development". That's actually a really good indicator for time and cost overruns. A req. doc. should also provide a storyboard of how the application interacts with the user, including screen mockups, flow diagrams, and screen state. It's usually very helpful to repeat the text with pictures. So, for example, if the requirement document says "when no row is selected the Delete and Update buttons should be grayed out" then it should also accompany this with a picture(s) and state diagrams that clearly define the requirements for button state. Nobody does detailed req. docs though, just as they don't do detail design docs or acceptance test procedures either. BTW, an ATP is the other side of the coin of a requirements doc. EVERY requirement should have an ATP line item to test whether the requirement is met. Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh SmithMarc Clifton wrote:
EVERY requirement should have an ATP line item to test whether the requirement is met.
I completely agree, but this is more to save on litigious cost ... personal note: be conserend when interacting with Lawyers.
You can only be young once. But you can always be immature. - Dave Barry
-
One challenge exposed: Requirement documentation is inheritly not complete. Different groups want different things from the new software. Marketing wants sellable taglines, Tech wants somthing fun to develop, Mangement wants to inprove shareholder wealth. With all of this complexity ... How is it posible that our current development system works? What or who is the driving factor to a successful deliverable?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
What or who is the driving factor to a successful deliverable?
ultimately the person who pays the $$ and grades your performance on the contract. Obviously, the more open it is the more difficult it is, which is why you need enough requirements to define the job, a little for everyone, but rigid enough that you can and will complete it. If you let everyone bicker, absolutely nothing will ever get done. Sofware is a product like an engine, it has parts, it has definable properties. You can get very very specific listing individual capabilities or more general in others. If the person wants to power a canoe with an outboard motor and you buy him a 16cyl engine for a Jaguar, obviously it is not going to work. Thus requirements, what must it do, in what environment. Treat it as an engineering product, with parts and pieces that function well together. Sales wants something with features that are incompatable with management requests, be honest and forth coming. It isn't that you don't want to build them, but they are incompatable, so you would recommend two products one for management and one for advertising, OR they can negotiate more compatible requirements.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Jason McBurney wrote:
Build Software X" is doomed for failure
because it has only (1) requirement. That is why it is doomed for failure. The requirements document says what Software X should do when completed, it should be succinct and remove as much fluff as reasonably possible. Software X: 1) UI a) .... b) .... c) .... 2) Network Interface a) .... b) .... c) .... 3) Platform/Compatibiltiy requirements a) .... b) .... c) .... when it is done it is also effectively a check list to see if you have completed the work. If you had a requirement of UI c) 'wxWidgets', but you preferred Qt (even though it costs more for commercial work), you just changed the document, and your own pass/fail. If they change it half way through then everything in wxWidgets has to be rewritten in Qt, meaning all the time spent already has to be redone, resulting in increased costs. This is why changes in the requirements adversely affect cost/delivery. Even though a UI interface API could be specified as a "what" item in the deliverables, it really should not be specified as "multi-document interface using 4 controls specifying xx on control 1, yy on control 2, zz on control 3 and aa on control 4" because now you treading dangerously on the "how" methodology which must be left to the software engineer. Since every "what" item costs more, specifying wxWidgets interface will cost more than allowing you to choose what ever is easiest/best for you. Specifying .Net should cost more too, even if it would be your primary choice, because it is a requirement, you just cut down your choices and restricted your development. YOU can always change your mind if things aren't working right, but if they restrict it for you, charge them.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
Jeffry J. Brickley wrote:
The requirements document says what Software X should do when completed
This is a nice link to Marc Clifton's comment: http://www.codeproject.com/lounge.asp?msg=1903728#xx1903728xx[^] Clifton suggests this should be taken to the story boarding level. Ironcially, I have seen very few (maybe one) req. doc. with a story board. Why do most req. doc look similar and not like a story board?
You can only be young once. But you can always be immature. - Dave Barry
-
Jeffry J. Brickley wrote:
The requirements document says what Software X should do when completed
This is a nice link to Marc Clifton's comment: http://www.codeproject.com/lounge.asp?msg=1903728#xx1903728xx[^] Clifton suggests this should be taken to the story boarding level. Ironcially, I have seen very few (maybe one) req. doc. with a story board. Why do most req. doc look similar and not like a story board?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
Clifton suggests this should be taken to the story boarding level.
that depends on the requirements, once again refer to the messages that each design will have its own differences. Storyboarding R&D concepts doesn't work becuase it is R&D and therefore doesn't exist, therefore can't be storyboarded. We do mostly R&D work. Since R&D carries the most risk, requirements documents originally came out of the R&D community where they have existed for many decades. Whether it is software engineering or hardware engineering, it comes down to a list of what "must" be done to successfully finish the job. Since most people don't write a document specific to their business, they tend to "borrow" a document from another department or another group (the internet has since perpetuated this even more-so), thus rarely does a requirements document exactly fit the business model of the project. If it did, it should include storyboarding with an "okay" from the operator with UI storyboarding. We have had one requirements document with a full UI storyboard, because we replaced an existing system, with existing trained people, we had to provide as near identical UI as possible such that no user training was "required" additional features would require additional training to the users, but existing features (of the replaced system) had to be recognizable to any trained personel. Thus we had full copies of exactly what that meant since without storyboarding that requirement, it would be so broad as to be unestimateable. Basically if you have to ask, "do I have enough information?" chances are you don't. If you have to ask, "can this be misinterpreted?" then you are not succinct enough. obviously a good relationship between contractor and client prior to and during the process is always a plus.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Marc Clifton wrote:
A req. doc. should also provide a storyboard of how the application interacts with the user, including screen mockups, flow diagrams, and screen state. It's usually very helpful to repeat the text with pictures. So, for example, if the requirement document says "when no row is selected the Delete and Update buttons should be grayed out" then it should also accompany this with a picture(s) and state diagrams that clearly define the requirements for button state.
Humm, What I am reading is ... People don't actually read requirement documents; therefore, the author must repeat himself many times? It is no wonder that nobody does detailed req. docs - The mangement folks, think these things are a waste of time... if we say the same thing in 4 ways ... they may have a point: How do requirement docs waste time?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
therefore, the author must repeat himself many times?
No, usually it helps to convey the same information in different formats to 1) make sure it's consistent and 2) sometimes mistakes in one format are discovered when trying to communicate the same thing in a different format.
Jason McBurney wrote:
How do requirement docs waste time?
I don't think they do, except when the person with the requirements really doesn't have a clue and keeps changing their mind. I've had that happen! Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh Smith -
Marc Clifton wrote:
EVERY requirement should have an ATP line item to test whether the requirement is met.
I completely agree, but this is more to save on litigious cost ... personal note: be conserend when interacting with Lawyers.
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
I completely agree, but this is more to save on litigious cost ... personal note: be conserend when interacting with Lawyers.
Actually, the ATP is often tied to milestone schedule and payments. Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh Smith -
Jason McBurney wrote:
therefore, the author must repeat himself many times?
No, usually it helps to convey the same information in different formats to 1) make sure it's consistent and 2) sometimes mistakes in one format are discovered when trying to communicate the same thing in a different format.
Jason McBurney wrote:
How do requirement docs waste time?
I don't think they do, except when the person with the requirements really doesn't have a clue and keeps changing their mind. I've had that happen! Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh SmithMarc Clifton wrote:
Jason McBurney wrote: How do requirement docs waste time? I don't think they do, except when the person with the requirements really doesn't have a clue and keeps changing their mind. I've had that happen!
Me too, which is the origin of this thread :)
You can only be young once. But you can always be immature. - Dave Barry
-
Jason McBurney wrote:
I completely agree, but this is more to save on litigious cost ... personal note: be conserend when interacting with Lawyers.
Actually, the ATP is often tied to milestone schedule and payments. Marc
People are just notoriously impossible. --DavidCrow
There's NO excuse for not commenting your code. -- John Simmons / outlaw programmer
People who say that they will refactor their code later to make it "good" don't understand refactoring, nor the art and craft of programming. -- Josh SmithI obviously don't have the same concept of ATP as you. What does ATP mean to you?
You can only be young once. But you can always be immature. - Dave Barry
-
I obviously don't have the same concept of ATP as you. What does ATP mean to you?
You can only be young once. But you can always be immature. - Dave Barry
The Acceptance Test Procedures that I've written, primarily for our dear government, consists of line by line steps to verify functionality of the hardware/software. It consists of sections, where each section/subsection validates a requirement, and the exact, precise, repeatable steps that are taken to verify that the requirement is met. Each line item is signed off and if it fails, notes are made as to why it fails, plan of action and/or acceptance due to a situation outside of the control of the testing process. Since gov't contracts (and others that I've worked on, for example, aeronautics industry is big on ATP's and milestones, in my experience) that I've worked on are based on completion of milestones, the ATP becomes a key vehicle for validating those milestones and hence payment.
Jason McBurney wrote:
I obviously don't have the same concept of ATP as you.
I've also noticed, in perusing the web for examples of an ATP, that my concept seems different. I guess my way of thinking is rather outdated. I did this stuff 20 years ago. However, some example similar to what I've done in the past can be found here[^] and here.[^] Of course, these are for hardware, but I've written them for software as well. Tedious, time consuming, but when you've got a couple hundred thousand dollars riding on acceptance, it's well worth it. And it also is a great document to work with while developing/debugging--you can have a grunt go through the ATP rather than a senior engineer. Here's a link on software ATP's[^] Acceptance’ is a significant stage in the contractual process; commercially, it is likely to