Requirements documentation
-
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