Due in class on October 22 with Presetations October 22 and 24

Assignment Requirements

This assignment consists of two parts: 1) a requirements document and 2) an in-class presentation. The content of the document is outlined below. Make it look professional but be practical (don't waste time). Requirements documents should be clear, complete, correct, and concise. Grading will be based on the content and quality of the requirements document and the oral presentation. The content of the oral presentation is outlined at the end of this page.

Note: Requirements specification documents and oral presentations will vary from project to project, and team to team. Use your judgement in selecting the best approach for your project and team.

Purpose and Content

Requirements documents serve many purposes. They specifiy the goals and scope of the project. In some cases, they are like a contract between the customer and the developers. They are the basis for testing. And in this project, the requirements document will also outline a development schedule.

A good requirements document desribes what the system will do, in a clear and unambiguous way. This can be achieved through careful wording, screen mock-ups or other graphics, and requirements analysis diagrams. A good requirements document can be used to answer questions such as: Is the system supposed to do X or not? How will the system handle it if the user does Y? Who will use the system and for what purposes? Under what environments (machine type, operation system, etc.) will the system work?

The requirements document will consist of

1. Title Page.
• names of team members
• date
• assignment name
• project name, nickname, logo
• version number (use version 1.0 when you hand in the document)
2. Summary. A two page summary of the project:
• Who's the customer?
• What's the project about?
• What are major functional and non-functional requirements?
• What is anticipated as an acceptance test?
• What are your target implementation platforms?
• Consider using a hierarchical organization: first a one paragraph overview emphasizing goals, then more details in the following paragraphs.
• Remember that the customer is going to read this. The customer's boss might read it too. Be clear and to-the-point. Avoid jargon. Avoid hype. Double-check spelling and grammar.
3. Glossary.
• Define any unusual words or unusual usage of common words, e.g., application domain terms.
4. Use Cases, Scenarios, Mock-up's.
• You may choose the best way to clarify and specify your systems funtionality. I suggest Mock-up's and Scenarios followed by an text outline of requirements. You may wish to specify Use Cases as you did in ICS 121.
• Some of you may choose diagrammatic presentations for complex functionality. You may use Sequence Diagrams, Activity Diagrams, etc.
• Some of you working on database functionality may choose to use entity relationship diagrams or another way to specify record designs.
5. Deliverables. What are you going to give to the customer? (include the items that apply)
• Software: Executables? In what format/media?
• Dococumentation: User's manual? On-line help? Web site? What will be in these documents?
• Development artifacts: Source code? Design docs? Test cases?
• Supporting artifacts: Example documents? Templates?
• Support: Warranty? Rights to bug fixes? Rights to request improvement?
  
6. Delivery Platform. What hardware/software/database/etc. will be needed to run the system? This is usually specified by your client.
7. Development Platform. What hardware/software/database/etc. will you need to develop the system? This is usually decided by you.
8. Milestones and Effort. A sequence of milestones. For each milestone:
• What requirements (functional or non-) are addressed.
• What will be accomplished.
• Date anticipated (remember there will be updates during weeks 6,7, and 8).
• Estimate of your effort and cost (state assumptions, e.g., cost of man hours).
9. Acceptance Test Plan. Be specific as possible. If you have specific data sets from your client, describe or include them.
10. Terms and Authorization. What sort of license agreement will you have for your software (open source, GNU, etc.)?
11. Conclusion. What will your team members gain as individuals and your team gain as a whole by doing this project? Perhaps you will talk about new skills? Tangibles? Intangibles?

Comments

Projects often begin vaguely. Clients do not have complete ideas about the work that should be done. They may not fully anticipate their needs. A requirements document starts to sort out the details and make them more clear for both you and the client.

Ideally, you will write the requirements in their "final" form. In reality, the requirements will be revised over time as you and the client learn more about the project. Emphasize clarity of intent and scope over very detailed specification of particular features. Try to meet with the customer to review and revise the document, if possible.

Try to use document formatting that enhances clarity and will be maintainable. Use numbered lists when order is important, bulleted list for unordered items. Use tables when there are lots of items (rows) that must have similar parts (columns), or when computing totals. Use mathematical notation, not English, to specify mathematical relationships. Use digarams or pictures to specify visual or spacial requirements.Make sure you can unambiguously refer to a specific part of the requirements document: for example, the customer might ask you if a certain requirement is satisfied yet, you want to be sure that you are both talking about the same requirement.

Grade yourself by using your document to answer these questions: What would it be like to use this system? What and how much can a user do with the system? If the customer is unhappy with the resulting system, can you confidently say "That is what you authorized when you signed the requirements document"? Would two people who read the same requirements document imagine the same system?

There are certain sections of the document where you need to write very precise English text. Ask yourself how each sentence could be misunderstood. Avoid words with vauge meanings or double meanings. Use specific amounts instead of vauge terms when possible. Include units in any measurements. Ask one of your team members to come up with a misinterpretation of what you wrote.

Requirements Presentations/Reviews

Each team should prepare a 15 minute presentation, after which we will allow up to 5 minutes of questions. Your customer should be present. 

Prepare your presentation appropriately. Your presentation should include the following:

• Title Slide (with team name, members, emails, date, etc
• Overview of your system (breif summary statement)
• Highlights of your requirements specification including
• Use Cases, Mock-up's, Scenarios, to communicate functionality
• Summary of required capabilities, with a diagram if available;

one or more detailed requirements for the most important capabilities
(pick the key issues to discuss in detail);
• Deliverables
• Delivery Platform, Development Platform
• Lifecycle considerations
• Current state of your project milestones with dates, noting potential exporsures/risks

(how you intend to develop the system throughout the lifecycle);
• System test plan

how you intend to both demonstrate that the system should be accepted as well as how you intend to convince yourselves that it is more than acceptable!).
• Technology Transfer, Maintenance, Other Considerations

Be sure to focus your presentation on the key issues. Don't spend time with the obvious things. If there's something in your presentation that you find boring, so will your audience. Don't gloss over problems. Your customer wants you to succeed, your instructors want you to succeed. They can't help you unless you tell them where you think the problems are, or are likely to be.