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
-
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...
-
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
And what they need-want-ask-for now is not always what they needed-wanted-asked-for for when they asked for it yesterday. And that is if they even know what they think they want. Most of my clients don't even know what they actually do, let alone what they want... X| ...and for some perverted reason, that is one of the reasons I love my job! ;P
-
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
To me a Requirements Document and Project Management Plan need to be created at the same time, and refined experientially during the Project. A static plan with heavy time schedules and tight budgets allows some control but does not always produce something the user community will adopt unless the scope is very limited. I am not convinced that a Requirements Document can be written once any more than code can be. It would be nice if the Analysis, Design, Coding, and Testing was linear, but in practice it is not. It is always experiential. What has helped me is to have a section that outlines what is NOT included as well as what is included. Otherwise it is too open-ended to be managed. The scope drifts and the project disintegrates. Developing each stage and step by including a review of the last step before finalizing the next step, allows Developer, QA, and User input. Adjusting the project with regularly scheduled meetings keeps it on target. The longer the review interval, the more project drift than can result. Letting Management and Users see interim results keeps the project relevant and builds loyalty. Not everyone likes consultants, sometimes for good reasons. But one of the best Books I found on this topic comes from Touche Ross - The System Development Process. These may not be popular ideas in the RAD world. I have found them to be what happens in practice. Selling management on them before getting into a project of any scope may be your best approach. Otherwise you may be the problem rather than the solution when the results are measured and the bouquets or bricks are thrown.
"Coding for fun and profit ... mostly fun"
-
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
...are really freaking boring to write. before i only had to write code, and we used to have these folks who kind of failed out of writing code...and made a career out of writing these things... they would burn all kinds of hours making the document looking fancy for the client (and we would always be short of coding hours and go over budget)... ...i don't recall ever reading one cuz my supe or lead would say "we need this ...", and i would go do it, and write some test harness for it...and it would get baselined. i am writing a requirements doc now... and it will NEVER have anything like "feedback on alpha or beta testing" in it... cuz i would never think about putting that kind of stuff mine. tell the dude he's out to lunch (nicely) :cool:
David
-
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
The main point to me is requirements' modifications occuring during alfa and beta testing. Usually, at this point the scope of reqs should have a rather crisp form. If a customer feedback is to have an influence to the reqs it should be treated as a change request (CR) with a clear assessment wrt risk/benefit. The modified req entry should contain a reference to the respective user feedback. I'd rather have alfa and beta feedback reports as a standalone document as it is a product evaluation rather than a definition.