Locked. This question and its answers are locked because the question is off-topic but has historical significance. It is not currently accepting new answers or interactions.
How do you go about the requirements gathering phase? Does anyone have a good set of guidelines or tips to follow? What are some good questions to ask the stakeholders?
I am currently working on a new project and there are a lot of unknowns. I am in the process of coming up with a list of questions to ask the stakeholders. However I cant help but to feel that I am missing something or forgetting to ask a critical question.
You're almost certainly missing something. A lot of things, probably. Don't worry, it's ok. Even if you remembered everything and covered all the bases stakeholders aren't going to be able to give you very good, clear requirements without any point of reference. The best way to do this sort of thing is to get what you can from them now, then take that and give them something to react to. It can be a paper prototype, a mockup, version 0.1 of the software, whatever. Then they can start telling you what they really want.
See obligatory comic below...
In general, I try and get a feel for the business model my customer/client is trying to emulate with the application they want built. Are we building a glorified forms processor? Are we retrieving data from multiple sources in a single application to save time? Are we performing some kind of integration?
Once the general businesss model is established, I then move to the "must" and "must nots" for the application to dictate what data I can retrieve, who can perform what functions, etc.
Usually if you can get the customer to explain their model or workflow, you can move from there and find additional key questions.
The one question I always make sure to ask in some form or another is "What is the trickiest/most annoying thing you have to do when doing X. Typically the answer to that reveals the craziest business/data rule you'll have to implement.
Hope this helps!
Steve Yegge talks fun but there is money to be made in working out what other people's requirements are so i'd take his article with a pinch of salt.
Requirements gathering is incredibly tough because of the manner in which communication works. Its a four step process that is lossy in each step.
I have an idea in my head
I transform this into words and pictures
You interpret the pictures and words
You paint an image in your own mind of what my original idea was like
And humans fail miserably at this with worrying frequency through their adorable imperfections.
Agile does right in promoting iterative development. Getting early versions out to the client is important in identifying what features are most important (what ships in 0.1 - 0.5 ish), helps to keep you both on the right track in terms of how the application will work and quickly identifies the hidden features that you will miss.
The two main problem scenarios are the two ends of the scales:
Not having a freaking clue about what you are doing - get some domain experts
Having too many requirements - feature pit. - Question, cull (prioritise ;) ) features and use iterative development
Yegge does well in pointing out that domain experts are essential to produce good requirements because they know the business and have worked in it. They can help identify the core desire of the client and will help explain how their staff will use the system and what is important to the staff.
Alternatives and additions include trying to do the job yourself to get into the mindset or having a client staff member occasionally on-site, although the latter is unlikely to happen.
The feature pit is the other side, mostly full of failed government IT projects. Too much, too soon, not enough thought or application of realism (but what do you expect they have only about four years to make themselves feel important?). The aim here is to work out what the customer really wants.
As long as you work on getting the core components correct, efficient and bug-free clients usually remain tolerant of missing features that arrive in later shipments, as long as they eventually arrive. This is where iterative development really helps.
Remember to separate the client's ideas of what the program will be like and what they want the program to achieve.
Some clients can create confusion by communicating their requirements in the form of application features which may be poorly thought out or made redundant by much simpler functionality then they think they require. While I'm not advocating calling the client an idiot or not listening to them I feel that it is worth forever asking why they want a particular feature to get to its underlying purpose.
Remember that in either scenario it is of imperative importantance to root out the quickest path to fulfilling the customers core need and put you in a scenario where you are both profiting from the relationship.
Wow, where to start?
First, there is a set of knowledge someone should have to do analysis on some projects, but it really depends on what you are building for who. In other words, it makes a big difference if you are modifying an enterprise application for a Fortune 100 corporation, building an iPhone app, or adding functionality to a personal webpage.
Second, there are different kinds of requirements.
Objectives: What does the user want to accomplish?
Functional: What does the user need to do in order to reach their objective? (think steps to reach the objective/s)
Non-functional: What are the constraints your program needs to perform within? (think 10 vs 10k simultaneous users, growth, back-up, etc.)
Business rules: What dynamic constraints do you have to meet? (think calculations, definitions, legal concerns, etc.)
Third, the way to gather requirements most effectively, and then get feedback on them (which you will do, right?) is to use models. User cases and user stories are a model of what the user needs to do. Process models are another version of what needs to happen. System diagrams are just another model of how different parts of the program(s) interact. Good data modeling will define business concepts and show you the inputs, outputs, and changes that happen within your program. Models (and there are more than I listed) are really the key to the concern you list. A few good models will capture the needs and from models you can determine your requirements.
Fourth, get feedback. I know I mentioned this already, but you will not get everything right the first time, so get responses to what your customer wants.
As much as I appreciate requirements, and the models that drive them, users typically do not understand the ramifications of of all their requests. Constant communication with chances for review and feedback will give users a better understanding of what you are delivering. Further, they will refine their understanding based on what they see. Unless you're working for the government, iterations and / or prototypes are helpful.
First of all gather the requirements before you start coding. You can begin the design while you are gathering them depending on your project life cicle but you shouldn't ever start coding without them.
Requirements are a set of well written documents that protect both the client and yourself. Never forget that. If no requirement is present then it was not paid for (and thus it requires a formal change request), if it's present then it must be implemented and must work correctly.
Requirements must be testable. If a requirement cannot be tested then it isn't a requirement. That means something like, "The system "
Requirements must be concrete. That means stating "The system user interface shall be easy to use" is not a correct requirment.
In order to actually "gather" the requirements you need to first make sure you understand the businness model. The client will tell you what they want with its own words, it is your job to understand it and interpret it in the right context.
Make meetings with the client while you're developing the requirements. Describe them to the client with your own words and make sure you and the client have the same concept in the requirements.
Requirements require concise, testable example, but keep track of every other thing that comes up in the meetings, diagrams, doubts and try to mantain a record of every meeting.
If you can use an incremental life cycle, that will give you the ability to improve some bad gathered requirements.
You can never ask too many or "stupid" questions. The more questions you ask, the more answers you receive.
According to Steve Yegge that's the wrong question to ask. If you're gathering requirement it's already too late, your project is doomed.
High-level discussions about purpose, scope, limitations of operating environment, size, etc
Audition a single paragraph description of the system, hammer it out
Mock up UI
Formalize known requirements
Now iterate between 3 and 4 with more and more functional prototypes and more specs with more details. Write tests as you go. Do this until you have functional software and a complete, objective, testable requirements spec.
That's the dream. The reality is usually after a couple iterations everybody goes head-down and codes until there's a month left to test.
Gathering Business Requirements Are Bullshit - Steve Yegge
read the agile manifesto - working software is the only measurement for the success of a software project
get familiar with agile software practices - study Scrum , lean programming , xp etc - this will save you tremendous amount of time not only for the requirements gathering but also for the entire software development lifecycle
keep regular discussions with Customers and especially the future users and key-users
make sure you talk to the Persons understanding the problem domain - e.g. specialists in the field
Take small notes during the talks
After each CONVERSATION write an official requirement list and present it for approving. Later on it would be difficult to argue against all agreed documentation
make sure your Customers know approximately what are the approximate expenses in time and money for implementing "nice to have" requirements
make sure you label the requirements as "must have" , "should have" and "nice to have" from the very beginning, ensure Customers understand the differences between those types also
integrate all documents into the latest and final requirements analysis (or the current one for the iteration or whatever agile programming cycle you are using ... )
remember that requirements do change over the software life cycle , so gathering is one thing but managing and implementing another
KISS - keep it as simple as possible
study also the environment where the future system will reside - there are more and more technological restraints from legacy or surrounding systems , since the companies do not prefer to throw to the garbage the money they have invested for decades even if in our modern minds 20 years old code is garbage ...
Like most stages of the software development process its iteration works best.
First find out who your users are -- the XYZ dept,
Then find out where they fit into the organisation -- part of Z division,
Then find out what they do in general terms -- manage cash
Then in specific terms -- collect cash from tills, and check for till fraud.
Then you can start talking to them.
Ask what problem they want you want to solve -- you will get an answer like write a bamboozling system using OCR with shark technoligies.
Ignore that answer and ask some more questions to find out what the real problem is -- they cant read the till slips to reconcile the cash.
Agree a real solution with the users -- get a better ink ribbon supplier - or connect the electronic tills to the network and upload the logs to a central server.
Then agree in detail how they will measure the success of the project.
Then and only then propose and agree a detailed set of requirements.
I would suggest you to read Roger-Pressman's Software Engineering: A Practitioner's Approach
Before you go talking to the stakeholders/users/anyone be sure you will be able to put down the gathered information in a usefull and days-lasting way.
Use a sound-recorder if it is OK with the other person and the information is bulky.
If you heard something important and you need some reasonable time to write it down, you have two choices: ask the other person to wait a second, or say goodbye to that precious information. You wont remember it right, ask any neuro-scientist.
If you detect that a point need deeper review or that you need some document you just heard of, make sure you make a commitment with the other person to send that document or schedule another meeting with a more specific purpose. Never say "I'll remember to ask for that xls file" because in most cases you wont.
Not to long after the meeting, summarize all your notes, recordings and fresh thoughts. Just summarize it rigth. Create effective reminders for the commitments.
Again, just after the meeting, is the perfect time to understand why the gathering you just did was not as right as you thought at the end of the meeting. That's when you will be able to put down a lot of meaningful questions for another meeting.
I know the question was in the perspective of the pre-meeting, but please be aware that you can work on this matters before the meeting and end up with a much usefull, complete and quality gathering.
I've been using mind mapping (like a work breakdown structure) to help gather requirements and define the unknowns (the #1 project killer). Start at a high level and work your way down. You need to work with the sponsors, users and development team to ensure you get all the angles and don't miss anything. You can't be expected to know the entire scope of what they want without their involvement...you - as a project manager/BA - need to get them involved (most important part of the job).
There are some great ideas here already. Here are some requirements gathering principles that I always like to keep in mind:
Know the difference between the user and the customer.
The business owners that approve the shiny project are usually the customers. However, a devastating mistake is the tendency to confuse them as the user. The customer is usually the person that recognizes the need for your product, but the user is the person that will actually be using the solution (and will most likely complain later about a requirement your product did not meet).
Go to more than one person
Because we’re all human, and we tend to not remember every excruciating detail. You increase your likelihood of finding missed requirements as you talk to more people and cross-check.
Avoid specials
When a user asks for something very specific, be wary. Always question the biases and see if this will really make your product better.
Prototype
Don’t wait till launch to show what you have to the user. Do frequent prototypes (you can even call them beta versions) and get constant feedback throughout the development process. You’ll probably find more requirements as you do this.
I recently started using the concepts, standards and templates defined by the International Institute of Business Analysts organization (IIBA).
They have a pretty good BOK (Book of Knowledge) that can be downloaded from their website. They do also have a certificate.
Requirements Engineering is a bit of an art, there are lots of different ways to go about it, you really have to tailor it to your project and the stakeholders involved. A good place to start is with Requirements Engineering by Karl Wiegers:
http://www.amazon.com/Software-Requirements-Second-Pro-Best-Practices/dp/0735618798/ref=pd_bbs_sr_2?ie=UTF8&s=books&qid=1234910330&sr=8-2
and a requirements engineering process which may consist of a number of steps e.g.:
Elicitation - for the basis for discussion with the business
Analysis and Description - a technical description for the purpose of the developers
Elaboration, Clarification, Verification and Negotiation - further refinement of the requirements
Also, there are a number of ways of documenting the requirements (Use Cases, Prototypes, Specifications, Modelling Languages). Each have their advantages and disadvantages. For example prototypes are very good for elicitation of ideas from the business and discussion of ideas.
I generally find that writing a set of use cases and including wireframe prototypes works well to identify an initial set of requirements. From that point it's a continual process of working with technical people and business people to further clarify and elaborate on the requirements. Keeping track of what was initially agreed and tracking additional requirements are essential to avoid scope creep. Negotiation plays a bit part here also between the various parties as per the Broken Iron Triangle (http://www.ambysoft.com/essays/brokenTriangle.html).
IMO the most important first step is to set up a dictornary of domain-specific words. When your client says "order", what does he mean? Something he receives from his customers or something he sends to his suppliers? Or maybe both?
Find the keywords in the stakeholders' business, and let them explain those words until you comprehend their meaning in the process. Without that, you will have a hard time trying to understand the requirements.
i wrote a blog article about the approach i use:
http://pm4web.blogspot.com/2008/10/needs-analysis-for-business-websites.html
basically: questions to ask your client before building their website.
i should add this questionnaire sheet is only geared towards basic website builds - like a business web presence. totally different story if you are talking about web-based software. although some of it is still relavant (e.g. questions relating to look and feel).
LM
I prefer to keep my requirements gathering process as simple, direct and thorough as possible. You can download a sample document that I use as a template for my projects at this blog posting: http://allthingscs.blogspot.com/2011/03/documenting-software-architectural.html
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 9 years ago.
Improve this question
I'm looking for a team building / training activity for some of my scrum teams. I want something that really illustrates the flexibility that the team has when implementing stories to define the scope and complexity of the feature themselves. Most of the teams have long-term waterfall experience and are used to having a well-defined specification. I'm looking for something that illustrates the need for the team to vary the scope of what they are building themselves, dependent on the time and resources available.
I couldn't find anything at tastycupcakes.com and Google wasn't much help. Maybe someone has prepared something themselves they would care to share?
Edit (in response to request for example in comments)
Suppose the team has committed to building a story for displaying data to a user in a paged list for analysis purposes. The acceptance criteria can be fulfilled easily but a differnet implementation might provide added functionality e.g. wrapping a third party control which has built-in sorting and grouping functionality.
The point is, because the scrum time window is absolutely fixed the scope of the implementation may be pushed if the team feels they are ahead of schedule, especially if some technical designs proved less problematic than thought. Conversely, if some tasks have taken longer than anticipated, the team can short-cut the user story while still making sure what they delivers satisfies the acceptance criteria.
The thing I am trying to get away from is the current mindset that the feature has a specification set in stone, and that's what will be built, whatever the circumstances.
I don't think it is up to the team to define the scope and complexity of a story. It is the PO's job to define the conditions of acceptance and then it is the team's job to estimate size based on the PO's description. If the stories are right sized, the conditions are usually pretty tightly defined. This could be why you aren't seeing much out there ....
EDIT:
I don't think your example changes my answer. If the PO wanted this "additional functionality" such as sorting etc, they would have defined it in the story or in another story. To build something that isn't asked for is waste. Spending time on a story that is low priority in the backlog is inefficient. Agile is based on building what is needed and only what is needed in order of importance. So I would frown on developers adding "extra goodies" just because they are working on a particular screen.
That does not mean you shouldn't look over all the stories in the backlog and make architectural plans based on what will be needed in the future.
I think I get what you're looking for, but feel free to clarify if I'm mistaken. I'm under the impression you're looking for an exercise that will show the flexibility in implementation details the team has when using user stories.
If so, try an exercise like this.
Split the team into two groups and have the same Product Owner between them (or you can have one Product Owner for each group if both PO's know the exercise).
The PO presents a fictional story like, "As an executive at BigSales Co, I want to be able to see, at a glance, which salespeople are performing and which are not, so that I can pair performers with under-performers to improve the overall team performance."
A story like the one above is light on implementation details, but has a very clear business problem to be solved (as user stories should). Using a story like this, give the teams 30 minutes to work on a paper prototype that would satisfy the user story. They can interact as much as they want with the PO during this time frame. The person playing the PO should be careful not to give them implementation details, but leave it to the team to decide, while expressing and clarifying the business need.
At the end of the 30 minutes, have each team present their solution and explain how it satisfies the user story.
The important thing here, is that once both teams have presented, it is likely that both presentations will be quite different and yet both valid. This shows the level of flexibility the team has to provide what they feel is the best solution without having to be told explicitly what to do.
Hope this helps.
In order to estimate the story cost the team will be expecting to work with the PO to define, in at least broad terms, the requirements for that feature. In the example you gave the team may explicitly ask the PO if the sorting & grouping functionality is needed. If they say no, as the PO can't see a use for it at that stage, then the estimate is given on that basis and the implementation done according to that. No consideration is given to these additional features on the YAGNI principle. If the requirement for the sorting & grouping comes up subsequently as a result of people using early incarnations of the product, well, that's another story, and is estimated & scheduled into the backlog accordingly. The scope of the implementation of a story isn't changed just because you've got some time left in an iteration - instead you simply pull the next prioritised item from the backlog and get on with that.
Of course, when implementing the story the team are at liberty to use the most time/cost effective method that they consider suitable for the evolving product. If this means using an component with additional capability i.e. a superset of the features then they could do so (unless this is in breach of non-functional requirements), as long as the acceptance criteria are passed, but they shouldn't go deliberately adding in unrequested functionality just because they've got some time spare in an iteration.
My opinion is somewhere between your description of adapting the features to the time, which is left, and the "just fulfill the acceptance criteria and that's it" POV of the two other commentators...
In my point of view, you all should recall the formal setup of an user story:
As a -role- I want -feature-, so -aim-.
Given the purpose of a desired feature, the developer can better understand, what the PO really wants. He then can come up with additional ideas and ask the PO, e.g.:
Hey PO, if you want -aim- so why don't we do -alternative/addition to feature-. Wouldn't that be even better?
And the PO may agree and the story is implemented as described, but in another interpretation, or the story maybe adapted. The points that is important to me:
The PO describes the purpose, he would like to have fulfilled, and a feature that is appropriate to do so
The team does not just implement the acceptance criterias like development zombies, but they are open minded and are tuned to the PO's vision in general and the single story purpose in particular - so they may come up with additional/alternative ideas.
The team also does not enhance user stories or over-engineer on their own authority. That's wasteful!
I hope you share my opinion ;-)
A good training exercise and a fun team building exercise is to do the XP Planning game.
The premise is that the product owner gives requirements for something visual (like a coffee machine, a robot) and all requirements must be drawable. The developers have to draw the requirements.
There are several short iterations (the whole exercise takes between an hour and 90 minutes depending on setup time) and it's interesting to see how communication improves and trade-offs happen as the game progresses. I've ran this myself during project kickoffs and when converting teams to agile practices and the team has always found it useful and fun.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
You can't just have user stories somehow the functionality of the program has to be documented. Do you end up with a specifications document with scrum? If you do do you end up assigning time to do this onto the task?
An example would be a complex workflow.
Another example would be a new member who comes onto the team.
There will be plenty of good ideas added to this question. My personal experience has taught me that:
1~ The working product is a form of documentation itself: assuming the product is accepted, then asking what it should do under certain condition is equivalent to asking what does it actually do under those conditions - log in and try it to get your answer.
2~ The tests, be them manual or automated (or a mix), are a form of documentation. Certainly unit tests may be way too far from the domain language spoken by the less-technically inclined team members (eg: 'business Experts', or Customers). Acceptance tests may be closer to a 'middle ground' of sort. Definitely BDD-style tests seem to have the best chance to build a ubiquitous language everyone can understand (see in this regard Gojko's Bridging the Communication Gap). Nonetheless, all of these form of tests are a form of documentation which can be used to determine what the product should do.
3~ Depending on where your project falls on the spectrum, your documentation (and, in general, all your ancillary artifacts) may require a higher or lower degree of ceremony. Smaller products, smaller teams, where time to market is critical may find that a very formal documentation of requirement costs way too much compared to the value it adds. Extremely large projects, spanning multiple teams and years of development, on the other hand, will find the ROI of formal documentation quite different.
4~ In the perfect world, we probably wouldn't need to document requirements other than in the form of working code (which, in the ivory Tower would also be self-explanatory) and tests (mostly for regression testing, and -on the fringe- to drive development of new features). Thus, the question of requirements documentation is a question about what's different between the Perfect World/Ivory Tower and the Real World/Trenches. The answer, of course, is different on a case-by-case, depending on the project and the team. For instance, we could say "All requirements shall be kept into this wiki, and maintained with the utmost care, etc etc..." but if the team is not familiar and comfortable with wikis this would not work.
5~ In the end, the stakeholders are those you should ask. Certainly, the topic should be approached in a collaborative manner, because everyone on the team will have to interact with the requirements throughout the project, but you must find a form of documentation that satisfy the stakeholders' needs.
All that being said, here's some places I've seen requirements documented while applying Scrum (why do I feel like this word should always be followed by an asterisk?):
PDF document
Bulletin Boards
Wiki
Wiki + Automated Acceptance Tests (read: FitNesse)
Unit tests
Manual Test Plans
User Stories, Use Cases diagrams (read: Enterprise Architect models)
Whiteboards around the office
Emails
Post-it notes
And, to be honest, I cannot say that any one system has a consistently higher correlation with a successful project than the others. I guess, indeed, we don't have a silver bullet.
HTH, thanks for the thought-provoking question!
Adding "documentation" as a task on each user story could certainly go a long ways towards your goal.
Scrum says you should document what you need, when you need it; it doesnt say you shouldnt have documents.
So if a document is required either by the finished product (eg. help documentation) or to produce the finished product (eg. requirements documentation) then there should be a documentation task/user story in your product backlog.
Appropriate priority should then be placed for that task.
For documentation the key point is;
Document only what you need, only when you need it.
You can't just have user stories
somehow the functionality of the
program has to be documented. Do you
end up with a specifications document
with scrum? If you do do you end up
assigning time to do this onto the
task?
Why can't you just have user stories? What purpose do these specification documents serve? What value does the investment in producing these documents return? Does the benefit out weigh the cost? If not, then isn't the time spent creating, and more importantly maintaining, these documents waste?
I know I'm asking more questions than providing answers, but I think part of what Scrum and other Agile approaches like lean do is force you to re-examine your current practices and see if they still make sense.
In the case of specifications, who will be updating and maintaining these documents once the feature has launched? In most companies I've been at, the documentation has been sparse, out of date, or rarely referenced.
Instead, why not use executable tests or BDD so that the documentation becomes part of the code and is executable. For example, see Ben Mabey's talk on Cucumber
If for some reason, a specific type of document is required for legal compliance purposes, you can always add it to the teams' definition of "done", however, I've found in most cases, stories and tests are more than sufficient forms of documentation.
Maybe my understanding of the question is completely wrong, but I what I understood was that the OP was uncomfortable with the mismatch between user stories and requirements. With reason I'd say.
In my opinion, user stories tell how a chunk of functionality shall be demonstrated to the product owner. The language of the story can be something that can be understood by the product owner but mainly by the developers. You might have stories that describe things that are not even directly required by the owner, but are breakdowns of things that are.
Requirements in the other hand are a detailed specification in domain user's language of what the system needs to do in order to be valid. In many cases a requirements document is not optional (fixed price projects for example).
What I do is a mix of both. I have a requirements document, and in most of my scrum stories, I have something in my notes that link that story with one or more items of the requirements. It is as simple as "See FR-042 and FR-45" (FR for functional requirement for example)
I think you are asking for a few different things here. If you are adding a new team member, then the documentation for the system should be geared toward their role on the team as part of the on-boarding process.
If you are talking about documenting the system functionality; in our organization our training teams document the functionality as part of the release. They are engaged (as a stakeholder) during the Sprint Review (demo) and then provided a training environment with the new functionality to prepare the training materials prior to release.
If you are talking about providing documentation for tractability, your backlog can serve as that with the proper process & controls added.
Each one of these different items takes planning and deliberate process development to effectively function and meet the needs of the team. We have included each one of these items in our retrospectives as an issue was identified and then developed our processes over time.
In addition to what James Kolpack said, the user story map should persist after the project is finished as it too is a form of documentation. I believe we plan to some how convert it to a document that lives in our Wiki when all is said and done.
The idea is that this document will be useful for people who need to maintain the system or add enhancements to it in the future because they will have an understanding of the user's perspective.
I mostly agree with Todd, but there was times when part of my team's task was to produce documentation : Documentation was the user story itself our PO asked to be delivered.
In these cases we followed the following guidelines:
try as much as we can to extract documentation from actual working code (typically some document generation program that read internal data structures or configuration files used both for building the actual program and build documents).
define in the documentation US the goal of the documentation :
who the reader is supposed to be
what he should be able to achieve reading that document.
In my experience that makes documents easier to write and enable some kind of test (you ask to someone, typically PO, to read the doc and say if it's OK considering the goal).
You write documentations to validate your system. User stories serve the same purpose if written correctly in a format that reflects user interaction with the system. I will recommend using BDD and writing stories using Gherkin syntax. Eventually your scenarios become your acceptance criteria which helps in validation whether the system is working correctly or not.
We have a docs team that produce the "instruction manual" for our product. The manual is structured around the main features of the product, and the tasks that the user can perform in those features.
Each sprint, Scrum teams work on user stories that add functionality to the product features.
After sprint planning, the docs team meet with the Scrum team and see which user stories that will be developed this sprint. The docs team then start enhancing the instruction manual by writing the initial docs. During the sprint, the docs team follow the progress of the user stories, and can use the product as it's deployed to test environments. At the end of the sprint, the docs team finialise the updated instruction manual and add final screen shots etc...
The instruction manual ship as part of the release each sprint.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
Does the functional spec help or hinder your expectations? Do programmers who practice the waterfall methodology, are they open to functional specs? I'm a web designer/developer working with a team of 5 programmers and would like to write a functional spec to explain what we need, so that when I begin my work - I know we are working towards the same goal.
I won't start any freelance project until I've got a design spec and functional spec written up and signed off. There's too much room for rogue clients to nickel and dime you to death if you don't have it. The functional spec allows you to stay on target/focused and gives you a natural check list to work to.
If there's no functional spec then you get all the "what ifs" starting to creep in and developers thinking - you know, this would be useful, and it'll only take me an hour. Sure an hour to code the prototype and get it basically working - plus the day to design all the tests and make sure all test cases are covered, then another couple of days to iron out all the bugs, then time to write the documentation. There's far too much room for what seems like a trivial addition to be inserted when there's no spec. You've no doubt heard of the infamous "scope creep". There's also far too much room for clients to say "that's not what I wanted..." when you deliver it and try and wriggle out of paying you.
If you've got the design spec and the functional spec written up ahead of the development and both you and the client have signed off that your understanding of not only the basic details but all the nuances of the language used is one and the same - only then can the real work begin.
There are a couple of anecdotes out there the first is quite true, while the other is a common misconception:
Software development is only 15% about the code, the rest is resource/people management.
It takes 20% of the time to complete the first 80% of the project and the remaining 80% of the time to complete the last 20%.
The misconception is that a working prototype is 80% of the way there - don't be fooled, it is not. So it's easy for a client to say "what's taking so long, I thought you were almost done!" and then quibble that they're paying too much for something that should've been finished months ago. Some of the design methodologies out there really lend themselves well to this popular misconception. The waterfall design methodology is one of them if it's not used correctly.
My view is make sure your understanding is the same, both sign off. Set milestones and make the client very aware at the outset that prototypes are a long way from the completion of the project and set expectations right from the outset as to what those milestones are and when the client can expect to see them delivered.
For project managers of development teams documentation and expectations are everything. You can't live without it, it's the only form of recourse you have against "That's not what I said" or "That's not what I meant" and ergo "I'm not paying you".
I learned from a lot of mistakes made by far more qualified developers than me and saw what it did to them. The two most important documents for your project are the design spec and the functional spec. Don't leave home without them or it can [or most likely will] come back and bite you in the ass.
Addendum re: User Stories:
An additional note about user stories is that they're great for what they are. They should be included in your functional specification but shouldn't be your functional specification.
A user story only describes a single task. It is very lightweight and doesn't contain excessive detail. As the common recommendations go, it should fit on a 3x5 card...if you as a project manager handed me a 3x5 card and told me to write a piece of software based on what I read, no doubt it would be handed to the user at the end and they'd tell the project manager that's not what they wanted.
You need a far greater level of detail in a functional spec. It shouldn't be limited to basic workflows. A functional spec is a whole bunch of user stories along with notes on interpretation of those user stories, improvements that can be made to them, common tasks that can be combined to improve efficiency. The list goes on.
So user stories are a good beginning, but they're not a replacement for a functional spec, they're bullet points in a functional spec.
I work with mostly the Waterfall model, and solely with functional specs. When working on my own (where I can set my own model and program any way I want) I start by writing up functional specs and then implementing them. It gives me a much better idea of the size and scope of the work, helps me estimate the time involved, and helps ensure that I don't miss anything.
Also, you can pass this document to:
Users so that they can make their requirements clear
Developers to create the functionality
Testers to make sure they are testing the right thing
Architects so that they can analyze the requirements
Using functional requirements over user stories is a matter of preference and the scope of the project. If you have a small user base, then you may be able to get away with user stories (which outline various event sequences the user might do), but for larger projects, you should use functional requirements as they have more detail and lead to fewer misunderstandings. Think of them as a means of communication with all people involved in the project.
Frankly, the Functional Specifications should already be part of your Big-M (Waterfall) methodology. Your functional specification is WHAT you are going to build; not necessarily how you are going to build it (which would be your detailed design/specification and the next step in the waterfall).
If you haven't written one yet, stop what you are doing and write one. You are just waste time if you do otherwise. You can start here with Joel's article.
It took me more than 10 years to get it beat into my head to write a functional spec before doing any code. Now I will write one for anything taking more than a day to write. The level of detail, and level of assumptions should be as much as needed to clearly define what needs to be done and communicate it to others (or remind yourself), anything beyond that is a waste.
Others prefer User Stories ... which is fine too, as long as you do some kind of planning.
Another way to accomplish this is using user stories
I find well-written functional specs very useful. A well organized functional specification can also help organize your tests (many-to-many mapping from individual requirements to test cases).
<p style="tongue: in-cheek">They also prove useful for finger-pointing in larger organizations (The requirements were inaccurate! The implementation didn't follow the requirement! QA didn't properly test this requirement! etc.)</p>
I'll second Codeslave's reference to Painless Functional Specification. It's a good series of articles on specifications. See also this Stackoverflow post for a discussion on what content to put into functional specs.
I've done a few large projects, including one with some hundereds of person-years of total effort. As a project team gets larger the number of informal communication channels goes up with a quadratic upper bound. Without a spec this informal communication mechanism is the only way things can get communicated. With a spec, the communication channels approach a hub-and-spokes, making the growth more like a linear function of the project team size.
A spec is really the only scalable way to to get the team 'singing off the same hymn sheet'. There should be some review and negotiation about the spec, but ultimately someone has to take ownership of this to avoid the project becoming a free-for-all.
I think they're a lovely idea, and should be tried.
Just a few comments on some of the answers here...
First of all, I do believe that a good spec document is important for any moderatly complex requirement (and definitly for highly complex ones). But make sure it is a good spec i.e. don't just state the obvious (like one poster already mentioned) but also don't leave out those parts that may seem trivial to you (or even the developers) since you might have more knowledge of that part of the system than some others involved (e.g. testers or documenters) which will appreciate the otherwise "missing bits".
And if your spec is good, it will get read - in my experience (and I've written and read lots of specs over the last years) it's the bad specs that get dumped and the good ones that get followed.
Concerning user stories (or sometimes also called use cases): I think these are important to get an idea of the scenario, but they usually can't replace the details (e.g. screen mockups, how where and if a feature is configurable, data model, migration issues etc.) so you'll probably need both for more complex requirements.
In my experience, functional specs have a fine line between not saying enough and saying too much.
If they don't say enough, then they leave areas open to misunderstanding.
If they say too much, they don't leave enough "wiggle room" to improve the solution.
And they should always be open to a process of revision.
It depends on the functional specification. I've had functional specifications where the writer knew the system inside and out, and wrote the specification as such, and I've had other writers write it with just what they expected to see as a user.
With the former, it's easier because I know exactly what I need to write and where I need to write it, but it limits how easily I can refactor the existing code, since estimates took into account just this feature, and not refactoring existing code that it touches.
With the latter, I have freedom to refactor (so long as end functionality is the same), but if it's a system I'm unfamiliar with, the time estimate is harder to make.
Overall, I love functional specifications -- I also like to remind people that they're written on paper that bends, and as such, should be flexible.
Whether you call them functional specs, business requirements, or user stories, they are all very beneficial to the development process.
The issue with them comes when they are chiseled in stone and used as a device to pass blame around when the system utimately doesn't fit with the user's real needs. I prefer to use the functionals or requirements as a starting point for an iterative process not as the bible for exactly how the system will look when it is complete. Things change, and users typically don't have an understanding of what they want until they have something (a working prototype possibly) in their hands that they can work with instead of conceptualizing on a piece of paper how it will function in the real world. The most successful projects I've implemented were ones where the development team and the users were closely aligned and were able to rapidly turn around changes instead of holding people to what they wanted on a piece of paper six months ago.
Of course this process wouldn't work if you were in a fixed-bid type of situation as one of the earlier answers pointed out.
One interesting substitute for a func spec or user stories that I have seen advocated is to write a user manual for the software first.
Even if this is only notional (i.e. if you do not intend to ship any manual - which you probably shouldn't as nobody will read it), it can be a useful and reasonably lightweight way to reach a common understanding of what the software will do and look like. And it forces you to do the design up front.
I've found that even if you write Functional Specs a lot of the detail is sometimes lost on the person you are trying to address. Now if a Functional Spec is written along with some kind of UI mockup, that makes a huge difference. UI mockups not only show the user what you are envisioning, it also triggers users into remembering things they wouldn't have thought off in the first place.
I have seen and written many specs, some were very good, most weren't. The main thing that they all had in common is that they were never followed. They all had cobwebs on them by the 3rd day of coding.
Write the spec if you want, the best time to do it is at the end of the project. It will be useless for developers to follow but it will at least be an accurate representation of what was done (I know- not really a spec). But don't expect the spec to get the code written for you. That is the real job. If you don't know what to write talk to your stakeholders and users and get some good user stories and then get on with it.
This is more of a business-oriented programming question that I can't seem to figure out how to resolve. I work with a team of programmers who have been working with BASIC for over 20 years. I was brought in to help write the same software in .NET, only with updates and modern practices. The problem is that I can't seem to get any of the other 3 team members(all BASIC programmers, though one does .NET now as well) to understand how to correctly do a relational database. Here's the thing they won't understand:
We basically have a transaction that keeps track of a customer's tag information. We need to be able to track current transactions and past transactions. In the old system, a flat-file database was used that had one table that contained records with the basic current transaction of the customer, and another transaction that contained all the previous transactions of the customer along with important money information. To prevent redundancy, they would overwrite the current transaction with the history transactions-(the history file was updated first, then the current one.) It's totally unneccessary since you only need one transaction table, but my supervisor or any of my other two co-workers can't seem to understand this. How exactly can I convince them to see the light so that we won't have to do ridiculous amounts of work and end up hitting the datatabse too many times? Thanks for the input!
Firstly I must admit it's not absolutely clear to me from your description what the data structures and logic flows in the existing structures actually are. This does imply to me that perhaps you are not making yourself clear to your co-workers either, so one of your priorities must be to be able explain, either verbally or preferably in writing and diagrams, the current situation and the proposed replacement. Please take this as an observation rather than any criticism of your question.
Secondly I do find it quite remarkable that programmers of 20 years experience do not understand relational databases and transactions. Flat file coding went out of the mainstream a very long time ago - I first handled relational databases in a commercial setting back in 1988 and they were pretty commonplace by the mid-90s. What sector and product type are you working on? It sounds possible to me that you might be dealing with some sort of embedded or otherwise 'unusual' system, in which case you do need to make sure that you don't have some sort of communication issue and you're overlooking a large elephant that hasn't been pointed out to you - you wouldn't be the first 'consultant' brought into a team who has been set up in some manner by not being fed the appropriate information. That said such archaic shops do still exist - one of my current clients systems interfaces to a flat-file based system coded in COBOL, and yes, it is hell to manage ;-)
Finally, if you are completely sure of your ground and you are faced with a team who won't take on board your recommendations - and demonstration code is a good idea if you can spare the time -then you'll probably have to accept the decision gracefully and move one. Myself in this position I would attempt to abstract out the issue - can the database updates be moved into stored procedures for example so the code to update both tables is in the SP and can be modified at a later date to move to your schema without a corresponding application change? Make sure your arguments are well documented and recorded so you can revisit them later should the opportunity arise.
You will not be the first coder who's had to implement a sub-optimal solution because of office politics - use it as a learning experience for your own personal development about handling such situations and commiserate yourself with the thought you'll get paid for the additional work. Often the deciding factor in such arguments is not the logic, but the 'weight of reputation' you yourself bring to the table - it sounds like having been brought in you don't have much of that sort of leverage with your team, so you may have to work on gaining a reputation by exceling at implementing what they do agree to do before you have sufficient reputation in subsequent cases - you need to be modded up first!
Sometimes you can't.
If you read some XP books, they often say that one of your biggest hurdles will be convincing your team to abandon what they have always done.
Generally they will recommend letting people who can't adapt go to other projects (Or just letting them go).
Code reviews might help in your case. Mandatory code reviews of every line of code is not unheard of.
Sometime the best argument is an example. I'd write a prototype (or a replacement if not too much work). With an example to examine it will be easier to see the pros and cons of a relational database.
As an aside, flat-file databases have their places since they are so much easier to "administer" than a true relational database. Keep an open mind. ;-)
I think you may have to lead by example - when people see that the "new" way is less work they will adopt it (as long as you don't rub their noses in it).
I would also ask yourself whether the old design is actually causing a problem or whether it is just aesthetically annoying. It's important to pick your battles - if the old design isn't causing a performance problem or making the system hard to maintain you may want to leave the old design alone.
Finally, if you do leave the old design in place, try and abstract the interface between your new code and the old database so if you do persuade your co-workers to improve the design later you can drop the new schema in without having to change anything else.
It is difficult to extract a whole lot except general frustration from the original question.
Yes, there are a lot of techniques and habits long-timers pick up over time that can be useless and even costly in light of technology changes. Some things that made sense when processing power, memory, and even disk was expensive can be foolish attempts at optimization now. It is also very much the case that people accumulate bad habits and bad programming patterns over time.
You have to be careful though.
Sometimes there are good reasons for the things those old timers do. Sadly, they may not even be able to verbalize the "why" - if they even know why anymore.
I see a lot of this sort of frustration when newbies come into an enterprise software development shop. It can be bad even when the environment is all fairly modern technology and tools. If most of your experience is in writing small-community desktop and Web applications a lot of what you "know" may be wrong.
Often there are requirements for transaction journaling at a level above what your DBMS may do. Quite often it can be necessary to go beyond DB transaction semantics in order to ensure time-sequence correctness, once and only once updating, resiliancy, and non-repudiation.
And this doesn't even begin to address the issues involved in enterprise or inter-enterprise scalability. When you begin to approach half a million complex transactions a day you will find that RDBMS technology fails you. Because relational databases are not designed to handle high transaction volumes you must often break with standard paradigms for normalization and updating. Conventional RDBMS locking techniques can destroy scalability no matter how much hardware you throw at the problem.
It is easy to dismiss all of it as stodginess or general wrong-headedness - even incompetence. But be careful because this isn't always the case.
And by the way: There are other models besides the RDBMS, and the alternative to an RDBMS is not necessarily "flat files" - contrary to the experience of of most coders today. There are transactional hierarchical DBMSs that can handle much higher throughput than an RDBMS. IMS is still very much alive in large IBM shops, for example. Other vendors offer similar software for different platforms.
Of course in a 4-man shop maybe none of this applies.
Sign them up for some decent trainings and then it's up to you to convince them that with new technologies a lot more is possible (or at least easier!).
But I think the most important thing here is that professional, certified trainers teach them the basics first. They will be more impressed by that instead of just one of their colleagues telling them: "hey, why not use this?"
Related post here.
The following may not apply in yr situation, but you make very little mention of technical details, so I thought I'd mention it...
Sometimes, if the access patterns are very different for current data than for historical data (I'm making this example up, but say that Current data is accessed 1000s of times per second, and accesses a small subset of columns, and all current data fits in less than 1 GB, whereas, say, historical data uses 1000s of GBs, is accessed only 100s of times per day, and access is to all columns),
then, what your co-workers are doing would make perfect sense, for performance optimization. By separating the current data (albiet redundantly) you can optimize the indices and data structures in that table, for the higher frequency access paterns that you could not do in the historical table.
Not everything that is "academically", or "technically" correct from a purely relational perspective makes sense when applied in an actual practical situation.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
We are a small team of 3 developers (2 experienced but new to this particular business sector) developing a functionally complex product. We're using Scrum and have a demo at the end of each sprint. Its clear that the functional team have plenty of ideas but these are not well communicated to the development team and the demo poses more questions than answers.
Have you any recommendations for improving the the quality of input from the functional people?
Further info: I think part of the problem is that there are no specs or User Stories as such. Personally I think they need to be writing down some sort of requirements - what sort of things should they be writing down and to what complexity given its an agile process?
Have you tried working with your customer to define / formulate acceptance tests?
Using something like Fit to come up with these tests - would result in better specs as well as force the customer to think about what is really required. The icing on the cake is instant-doc-executable specs at the end of this process.
That is of course, if your customers are available and open to this approach. Give it a try!
If not (and that seems to be the majority - because it is less work) - calendar flash 'em - schedule meetings/telecons every week until they sing like canaries :) +1 to Dana
Sometimes the easiest way to get input from people is to force it out of them. My company used SCRUM on a project, and found very quickly that people tend to keep to themselves when they already know what they're doing. We ended up organizing weekly meetings where team members were required to display something that was learned during the week. It was forced, but it worked pretty well.
I'm a big believer in Use Cases, detailing the system behaviour in response to user actions. Collectively these can form a loose set of requirements, and in a SCRUM environment can help you prioritise the Use Cases which will form that particular sprint's implemented features.
For example, after talking to your functional team you identify 15 separate Use Cases. You prioritise the Use Cases, and decided to plan for 5 sprints. And the end of each sprint you go through and demo the product fulfilling the Use Cases implemented during the sprint, noting the feedback and amending the Use Cases.
I understand that the people you call functional people are acting as Product Owners, right?
I think part of the problem is that there are no specs or User Stories as such. Personally I think they need to be writing down some sort of requirements - what sort of things should they be writing down and to what complexity given its an agile process?
Actually, without having any specs you probably have no acceptance test for the backlog itens as well. You should ask the PO to write the user stories, I like the "As a - type of user -, I want -some goal- so that -some reason-." form. Keep in mind that the User Stories shall be INVEST - Independent, Negotiable, Valuable to users or customers, Estimable, Small and Testable. What is a must is to have the Acceptance tests written together with the story so that the team should know what the story must be able to do in order do be set as done.
Remember that as the product evolves, it's expected to the PO have ideas as he sees the working product. It's not a bad thing, actually it is one of the best thing you can get through Agile. What you have to pay attention is that this ideas mus be included in the product backlog and it needs to be prioritized by th PO. And, if it's necessary and will add value to the customer, the idea should be planned to be built in the next sprint.
Someone from the functional team should be part of the team and available to answer your questions about the features you're adding.
How can you estimate the Backlog item if they are not detailled enough ?
You could establissh a rule that Backlog item that do not have clear acceptance criteria cannot be planned.
If would be better to have someone from the functional team acting as Product Owner, to determine, choose and priotitize the Backlog items, and/or as Domain Expert.
Also, make sure everyone in both the functional team and the development team speaks the same language, so as to avoid misunderstandings ; See ubiquitous language.
Track the time most waiting for answers from the functional team as well as he time wasted developping unnecessary features or reworking existing features so that they fits the bill.
Are they participating in the stand-up meetings?
You could propose to have a representative at each (or some) of them, to ask them for input before the end of the sprint
Are you doing stand-up meetings and do you have burn down chart? I think those two areas would benefit you greatly.
I recommend the book "Practices of an agile developer" it is full of suggestions how to make a scrum team successful. It also gives good tips how to get the product owner/customer more involved and how to get the whole process rolling. It's worth the money IMHO.
I agree that you need some sort of requirements (user stories or else).
One piece of advice I can give is to use some sort of visual aids with the functional teams. When customers have plenty of ideas (as you've said) they usually also have a visual idea of what a feature looks like, when the developed product doesn't fit this visual idea it creates a lot of doubts, even if it does the job functionally.
When discussing functionality with customers, I try to be very visual. Drawing sketches on a board, or even verbally describing what something would look like. Trying to find a common visual image. You can then take a photo of the sketches and use them as part of the documentation.
Another advice is to keep your sprints as short as possible, so that you do more frequent demos. But you may already be doing this, since you didn't mention your current sprint duration.