What to include in requirements documentations
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
You're entirely correct; user feedback is reference material, not requirement documentation. A requirements document is a specification, and can be a contract document, even internally if several departments or individuals are involved in the development. Treat it with respect, and don't allow any deviation without a formal process involving all the players. User feedback is source material from which formal requirements are developed; keep the source in a file somewhere, but don't stuff it in the official documentation. As a rule, if it can't be measured quantitatively, or ticked off on a checklist during test or check-in, it's not a requirement, it's a comment.
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
-
I agree with you 100%. Requirement documents are NOT design documents. (Of course, where I work now, even requirements memos would be welcome.)
Anyone who thinks he has a better idea of what's good for people than people do is a swine. - P.J. O'Rourke
I'd love a requirements doc. We do get the odd change request (user feedback?) but a requirements doc - not a chance.
Never underestimate the power of human stupidity RAH
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
Mark Nischalke wrote:
My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
i agree, it should be put into the next cycle of development requirements or something otherwise you are asking for a rolling spec which is the never ending carrot infront of the donkey...
-
Feedback should influence the requirements. Generally it doesn't become the requirements. What people actually want, and what they ask for, are sometimes quite different.
Graham Bradshaw wrote:
What people actually want, and what they ask for, are sometimes quite different.
Only sometimes? :~
Nobody can give you wiser advice than yourself. - Cicero .·´¯`·->Rajesh<-·´¯`·. Microsoft MVP - Visual C++[^]
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
Yer just beggin' for unmanageable scope creep by making user feedback a part of the requirements doc. Version 1 should provide what was agreed on in the initial signed requirements document (unless there's a REALLY big breakdown of functionality), then features based on feedback can be added as a version 1.1 after the appropriate financial negotiations. Been there, done that, still got the burn marks.
-
All requirement documents should include a stipulation that the PM always takes the blame when things go wrong.
No, the contractor/consultant always takes the blame. If one can't live with that, then they should never consider being a contractor/consultant. I always start out every project by saying something like "Well, since as the gringo consultant, I'm going to take the blame for this at the end, let's talk about what you're going to blame me for."
The PetroNerd
Walt Fair, Jr. Comport Computing Specializing in Technical Engineering Software
-
Clear up what "requirements document" means: A software requirements specification (SRS) is a complete description of the behavior of the system to be developed wikipedia[^] (emphasis by me) It is NOT a collection of every requirement uttered, but it defines what you will actually DO - and that incldues what you will NOT do. Requirement analysis means 1. Collecting all the wishes and ideas 2. Weed out the crap 3. Sign what you will do Otherwise, this generic requirements list could be used: Requirements: Has pr0n background image. [Joe User] Makes one point five gazillion money. Or maybe two point three. [board of directors] People will love it so much, they'll force their friends to buy it, too. [Director of Marketing] Can be used by an untrained monkey. [Helpdesk Sue] Takes no more than two weeks to implement in Excel. [Human Resosurces]
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistTraditional Requirement Documents are great, but I have found greater success in the SCRUM methodology. You could spend weeks to even months getting wrapped around requirement documents before any development actually happens. Sure there are some that may be skeptical with SCRUM for various reasons. Some people may like to deal with evolving requirement documents, but I personally don't. :) Any developer knows that the customer can always change their mind in the next release, and typically that is what happens. http://en.wikipedia.org/wiki/Scrum_(development)[^]
-
Traditional Requirement Documents are great, but I have found greater success in the SCRUM methodology. You could spend weeks to even months getting wrapped around requirement documents before any development actually happens. Sure there are some that may be skeptical with SCRUM for various reasons. Some people may like to deal with evolving requirement documents, but I personally don't. :) Any developer knows that the customer can always change their mind in the next release, and typically that is what happens. http://en.wikipedia.org/wiki/Scrum_(development)[^]
Thank you for your comment. When I strip all the funny names from scrum, all that's left is a set of rules: now the requirements document is frozen, and now it can move again. At least, that's what the developer sees. All schedule pressure is put on one single role - the Project Owner, and he is to keep it from the developers. I don't think that's bad, mind you. At its core, it keeps the developers on what they love most - implement features - and stops the boss from storming into the office, shouting "drop what you are doing, how fast can we have Feature X?" You still have a requirements document. Some basic truths are still truths. I have doubts about Scrum being universally better. Even in an agile setting which tests tests tests tests, bugs will happen, bugs that stop customers from using the features they paid for. A schedule change will usually take almost two sprints to be available. Is that ok for your product? Will the requirenments remain frozen if the version to demo at a trade show contains a big bad ugly showstopper?
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighist -
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
If you wait for the alpha and beta testing, which should be actions that verify the system developed meets the requirements, it seems to be too late. User feedback should be done prior to any development and should be done by the project sponsor as verification that they know what they are talking about when explaining the requirements of the system to satisfy their business need. Some will base requirements on what they create, while others create based on the requirements defined. Which system would you prefer to get delivered for your business?
-
Thank you for your comment. When I strip all the funny names from scrum, all that's left is a set of rules: now the requirements document is frozen, and now it can move again. At least, that's what the developer sees. All schedule pressure is put on one single role - the Project Owner, and he is to keep it from the developers. I don't think that's bad, mind you. At its core, it keeps the developers on what they love most - implement features - and stops the boss from storming into the office, shouting "drop what you are doing, how fast can we have Feature X?" You still have a requirements document. Some basic truths are still truths. I have doubts about Scrum being universally better. Even in an agile setting which tests tests tests tests, bugs will happen, bugs that stop customers from using the features they paid for. A schedule change will usually take almost two sprints to be available. Is that ok for your product? Will the requirenments remain frozen if the version to demo at a trade show contains a big bad ugly showstopper?
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistYou still have a requirements document. Some basic truths are still truths. The statement above is true. The requirement document can be viewed as the gospel, so to speak, or a guideline. I never liked the idea of a requirements document being used as something set in stone, because as we all know the customer typically knows what he/she wants, but he/she doesn't "KNOW" what he wants. Hence some truths are still truths. With that being said I have seen quicker turn around with SCRUM then a requirements document, but there again that is just my personal experience, and if people have more success using a requirement document to manage their projects more power to them. In the end, if mama (the customer) is happy than everybody is typically happier.
-
You still have a requirements document. Some basic truths are still truths. The statement above is true. The requirement document can be viewed as the gospel, so to speak, or a guideline. I never liked the idea of a requirements document being used as something set in stone, because as we all know the customer typically knows what he/she wants, but he/she doesn't "KNOW" what he wants. Hence some truths are still truths. With that being said I have seen quicker turn around with SCRUM then a requirements document, but there again that is just my personal experience, and if people have more success using a requirement document to manage their projects more power to them. In the end, if mama (the customer) is happy than everybody is typically happier.
SoonerArtie wrote:
With that being said I have seen quicker turn around with SCRUM then a requirements document, but there again that is just my personal experience, and if people have more success using a requirement document to manage their projects more power to them.
I still see scrum as a specific way to work with the requirements document, not a way to get rid of it. What works best strongly depends on the type of project and the team - scrum "intuitively" makes sense for many projects, I agree.
SoonerArtie wrote:
In the end, if mama (the customer) is happy than everybody is typically happier.
I disagreee. And the mantra of scrum seems to be keep the developers happy. :D
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighist -
peterchen wrote:
"facilitating leverages"
For a moment there, I read "facilitating beverages" (whether it be Dr. Pepper or :beer: ) :laugh:
"The clue train passed his station without stopping." - John Simmons / outlaw programmer "Real programmers just throw a bunch of 1s and 0s at the computer to see what sticks" - Pete O'Hanlon
go ahead! :D
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighist -
Traditional Requirement Documents are great, but I have found greater success in the SCRUM methodology. You could spend weeks to even months getting wrapped around requirement documents before any development actually happens. Sure there are some that may be skeptical with SCRUM for various reasons. Some people may like to deal with evolving requirement documents, but I personally don't. :) Any developer knows that the customer can always change their mind in the next release, and typically that is what happens. http://en.wikipedia.org/wiki/Scrum_(development)[^]
The best methodology is what works for you or the organization. Even with scrum or agile you don't just start off building something, there is planning that goes into.
only two letters away from being an asset
-
SoonerArtie wrote:
With that being said I have seen quicker turn around with SCRUM then a requirements document, but there again that is just my personal experience, and if people have more success using a requirement document to manage their projects more power to them.
I still see scrum as a specific way to work with the requirements document, not a way to get rid of it. What works best strongly depends on the type of project and the team - scrum "intuitively" makes sense for many projects, I agree.
SoonerArtie wrote:
In the end, if mama (the customer) is happy than everybody is typically happier.
I disagreee. And the mantra of scrum seems to be keep the developers happy. :D
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistpeterchen wrote:
I disagreee. And the mantra of scrum seems to be keep the developers happy. [Big Grin]
The reason I made the previous comment is that I find it gives flexibility on both ends, not just the developer. The customer isn't chained to what they thought they meant when they said X,Y,Z in the requirements document in previous months. That is why it makes our customer happy. :)
-
The best methodology is what works for you or the organization. Even with scrum or agile you don't just start off building something, there is planning that goes into.
only two letters away from being an asset
In our case we used a both/and approach a requirements document (a guideline if you will), but we took it further with the SCRUM approach. Yes, I agree with you it is what works best for your organization.
-
go ahead! :D
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistIt is a planned part the evening endgame to do some facilitation of beverages :rolleyes:
"The clue train passed his station without stopping." - John Simmons / outlaw programmer "Real programmers just throw a bunch of 1s and 0s at the computer to see what sticks" - Pete O'Hanlon
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
Mark Nischalke wrote:
They want to add user feedback from alpha and beta testing to the document.
Sounds like some-one at your business needs to open a book that describes "Change Control". A lot of people mix up "Change Control" with "version control" (aka "configuration management"). They're different. Once you are aware of your options wrt Change Control, you are in a position to make a decision that bests suits your situation. hth.
-
Feedback should influence the requirements. Generally it doesn't become the requirements. What people actually want, and what they ask for, are sometimes quite different.
Graham Bradshaw wrote:
What people actually want, and what they ask for, are sometimes quite different.
and what they actually need may not be that for which they ask, nor what you think they want.
TUT Sancta Simplicitas
-
No not a programming question, just an opinion and common practice question. We have recently been having a lively discussion at work with our tech writer and PM about what to include in the requirements documents. They want to add user feedback from alpha and beta testing to the document. My opinion is that the actual feedback doesn't belong there. It should be stored elsewhere and incorporated into the requirements.
only two letters away from being an asset
In my experience, raw feedback from users practically never contains real requirements. I don't remember a single user who could "speak requirements". Well, unless he/she is directly answering certain questions very precisely crafted by a business analyst (in which case I would not call those answers "raw user feedback" ;) ). Typically, requirements have to be "extracted" from user feedback. Therefore I believe that, semantically, raw user feedback is nothing more than source material for requirements, but not a part of requirements. It is incredibly important, but only supplementary information, if you wish. As for logical/physical documentation organization... I think the proper place for user feedback should depend more on technical issues than on semantic ones. If it is really necessary to have one big linear document (like a book) containing not only requirements themselves but all supplementary information, then I do not see any problem with turning user feedback into one of the appendices; after all, appendices would be exactly where all supplementary info should go in such case. However, I think that nobody really needs a single fat "requirements book", and any supplementary info (including user feedback) is perfect candidate for separate documents (or even a database) hyperlinked or otherwise referenced by the document(s) containing actual requirements. BTW, IMHO it is much more important to provide some minimal structure in the document(s) containing raw user feedback. At least, it should be as easy as possible to make references to various fragments in that document. Such references might be very useful when providing justifications or other comments for actual requirements, as well as when discussing requiremens' severities and priorities. Just my 2 cents...