Requirements documentation
-
What makes good requirement documentation? Have you ever read a "Requirement" document, and felt less that satified. In contrast, what have been your experience with "Good" requirement documents?
You can only be young once. But you can always be immature. - Dave Barry
a good requirement document must have a penality clause that states that any modification to the requirements at different stage of the project will have increasing impact on the cost of the project (in time and in money) and should state who will make modifications to the requirements, and who will have to approve them. And must be signed by every party involved.
Maximilien Lincourt Your Head A Splode - Strong Bad
-
What makes good requirement documentation? Have you ever read a "Requirement" document, and felt less that satified. In contrast, what have been your experience with "Good" requirement documents?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
What makes good requirement documentation?
http://www2.sims.berkeley.edu/courses/is208/s02/ReqsDoc.pdf[^] it's a bit general, but decent explanation of the process.
Do not do any work that costs you more than it is worth to you._________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
a good requirement document must have a penality clause that states that any modification to the requirements at different stage of the project will have increasing impact on the cost of the project (in time and in money) and should state who will make modifications to the requirements, and who will have to approve them. And must be signed by every party involved.
Maximilien Lincourt Your Head A Splode - Strong Bad
Is it reasonable to assume everyone knows everything when they start? Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
You can only be young once. But you can always be immature. - Dave Barry
-
Jason McBurney wrote:
What makes good requirement documentation?
http://www2.sims.berkeley.edu/courses/is208/s02/ReqsDoc.pdf[^] it's a bit general, but decent explanation of the process.
Do not do any work that costs you more than it is worth to you._________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
Although this is good theory, in your experiance, does it work? The funamental proposal of her paper is to abstract the how from the what? How many buisiness people do you hear wanting to use ... .Net for they new process? Advertizing budgets conflict with this abstraction priciple; therefore, What is the aim of a good requirement document?
You can only be young once. But you can always be immature. - Dave Barry
-
Is it reasonable to assume everyone knows everything when they start? Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
how does that improve our Requirements
The requirements should only included "what" should be done, not how. The company can understand that the "what" are each deliverable entities, and like buying individual parts of a complex product: you buy more, it costs more. If you treat it as a business model, so will they. If you treat the entire product as one object and "free" design within, they will keep adding more to the design. Treat each requirement, each "what it does" object as a deliverable. Your estimate and your costs are based one the "what" if they add more, they should expect to pay more. It comes down to how you bring your product to the table.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Is it reasonable to assume everyone knows everything when they start? Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
it makes it clear that if someone wants to change the parts of the requirements it will have impact on the whole project; and that costs money. If at some point in the life of the software, someone decide to make a change in the requirement that will impact the specifications that will impact the architecture and will impact the data structure, it will be harder to make those changes while keeping the original schedules and release timelines.
Maximilien Lincourt Your Head A Splode - Strong Bad
-
Is it reasonable to assume everyone knows everything when they start? Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
You can only be young once. But you can always be immature. - Dave Barry
It's true that customers need to be aware of the costs involved when they want to change requirements. But I also think there should be room for discussion along the road to release. However, you have to trade features or requirements when the customer wants something changed. My opinion is that you need to have the large pieces of functionality on paper at the beginning and work out the details during the design phase and building phase of the project. I think that risk management is key here, the best thing you can do is be sure that the parts with the highest risk are identified and worked out the first in the project. The rest is doable most of the time when you have worked out the high risk parts.
WM. What about weapons of mass-construction? "What? Its an Apple MacBook Pro. They are sexy!" - Paul Watson
-
Jason McBurney wrote:
Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements?
it makes it clear that if someone wants to change the parts of the requirements it will have impact on the whole project; and that costs money. If at some point in the life of the software, someone decide to make a change in the requirement that will impact the specifications that will impact the architecture and will impact the data structure, it will be harder to make those changes while keeping the original schedules and release timelines.
Maximilien Lincourt Your Head A Splode - Strong Bad
Maximilien wrote:
Jason McBurney wrote: Business folks inheritently want to get things done, penalitizing them - how does that improve our Requirements? it makes it clear that if someone wants to change the parts of the requirements it will have impact on the whole project; and that costs money.
As I understand, Requirments; per our conversation, is a second phase item. Inherintly, the goal of the requirements documentation is to communicate the ramifications of the solution that we intend on developing as technical individuals. The first item in the process, is the business proposal for a product? An RFP?
You can only be young once. But you can always be immature. - Dave Barry
-
Although this is good theory, in your experiance, does it work? The funamental proposal of her paper is to abstract the how from the what? How many buisiness people do you hear wanting to use ... .Net for they new process? Advertizing budgets conflict with this abstraction priciple; therefore, What is the aim of a good requirement document?
You can only be young once. But you can always be immature. - Dave Barry
Jason McBurney wrote:
How many buisiness people do you hear wanting to use ... .Net for they new process?
that is still a "what" because it is the foundation platform from which the design originates. If source code is turned over (preferrably not, or charge much more), they can specify languages as well. A customer can and does often specify the hardware platform (Windows PC, Mac, Linux, Sun, IBM blade, etc), they can also specify just a loose OS reference (Windows, Linux, OS X) without hardware references. So too with .Net they are specifying a platform from which to run. Yes that gets into "how" per se, but it may be because they have other .Net software to attach to it. Chances are they don't know enough about the platform, or don't want to know, but know what they want to be compatible with. Sometimes they just need the advertising ("we're .Net! hurah!") etc. A customer will always try to specify more, or push the limits, they want the most for their money. But as requirements add up, and the costs adds for each change, AND if it is explained right, the point can be made. Yes it works, that document is a bit too general for our requirements documents, but we are graded on requirements completed, how well, and how fast, downgraded for going over or under estimates (where-as other customers would be happy for coming in underbudget). But it does work if you keep the "how" out of it for the most part. In our case some "how" functionality must be in the requirements document from a technology stand-point. Each product must have a certain level of new, and existing technology, so you are addressing this as still a platform (what) concept, but it is really a "how" it is to be done. But again, it is addressed as a "what" item still in the requirements document.
_________________________ 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:
how does that improve our Requirements
The requirements should only included "what" should be done, not how. The company can understand that the "what" are each deliverable entities, and like buying individual parts of a complex product: you buy more, it costs more. If you treat it as a business model, so will they. If you treat the entire product as one object and "free" design within, they will keep adding more to the design. Treat each requirement, each "what it does" object as a deliverable. Your estimate and your costs are based one the "what" if they add more, they should expect to pay more. It comes down to how you bring your product to the table.
_________________________ 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 should only included "what" should be done, not how.
I strongly agree! However, it sounds like the core issue with requirements is the process that IT uses to construct them. Having a single goal "Build Software X" is doomed for failure, and cost overruns. In contrast, if the goal was to Provide a "Path finding discussion for Software X" and "Goal analysis document" for software X, then it would follow the requirements document would be more complete? Why then does IT have weak process as it applies to software design?
You can only be young once. But you can always be immature. - Dave Barry
-
It's true that customers need to be aware of the costs involved when they want to change requirements. But I also think there should be room for discussion along the road to release. However, you have to trade features or requirements when the customer wants something changed. My opinion is that you need to have the large pieces of functionality on paper at the beginning and work out the details during the design phase and building phase of the project. I think that risk management is key here, the best thing you can do is be sure that the parts with the highest risk are identified and worked out the first in the project. The rest is doable most of the time when you have worked out the high risk parts.
WM. What about weapons of mass-construction? "What? Its an Apple MacBook Pro. They are sexy!" - Paul Watson
WillemM wrote:
It's true that customers need to be aware of the costs involved ... also [I] think there should be room for discussion along the road to release.
WillemM wrote:
I think that risk management is key here, the best thing you can do is be sure that the parts with the highest risk are identified and worked out the first in the project.
Yes, if this is the case then why when I read a requirement document, in general, is the risk section either nonexistant, TBD, or blank? Who then is the best role to identify the risk of different elements of the software? Techincal, business, or Mangement?
You can only be young once. But you can always be immature. - Dave Barry
-
What makes good requirement documentation? Have you ever read a "Requirement" document, and felt less that satified. In contrast, what have been your experience with "Good" requirement documents?
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 Smith -
Jeffry J. Brickley wrote:
The requirements should only included "what" should be done, not how.
I strongly agree! However, it sounds like the core issue with requirements is the process that IT uses to construct them. Having a single goal "Build Software X" is doomed for failure, and cost overruns. In contrast, if the goal was to Provide a "Path finding discussion for Software X" and "Goal analysis document" for software X, then it would follow the requirements document would be more complete? Why then does IT have weak process as it applies to software design?
You can only be young once. But you can always be immature. - Dave Barry
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)
-
Jason McBurney wrote:
How many buisiness people do you hear wanting to use ... .Net for they new process?
that is still a "what" because it is the foundation platform from which the design originates. If source code is turned over (preferrably not, or charge much more), they can specify languages as well. A customer can and does often specify the hardware platform (Windows PC, Mac, Linux, Sun, IBM blade, etc), they can also specify just a loose OS reference (Windows, Linux, OS X) without hardware references. So too with .Net they are specifying a platform from which to run. Yes that gets into "how" per se, but it may be because they have other .Net software to attach to it. Chances are they don't know enough about the platform, or don't want to know, but know what they want to be compatible with. Sometimes they just need the advertising ("we're .Net! hurah!") etc. A customer will always try to specify more, or push the limits, they want the most for their money. But as requirements add up, and the costs adds for each change, AND if it is explained right, the point can be made. Yes it works, that document is a bit too general for our requirements documents, but we are graded on requirements completed, how well, and how fast, downgraded for going over or under estimates (where-as other customers would be happy for coming in underbudget). But it does work if you keep the "how" out of it for the most part. In our case some "how" functionality must be in the requirements document from a technology stand-point. Each product must have a certain level of new, and existing technology, so you are addressing this as still a platform (what) concept, but it is really a "how" it is to be done. But again, it is addressed as a "what" item still in the requirements document.
_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
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:
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
-
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:
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
-
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