CS 361 Project Documents

Date of last update: Feb. 26, 2008.
Status: Requirements, Project Plan, and Design specs are up-to-date. However, a few additional clarifications may be later added.

The Project:

What actually is the project? It is to design software. To tie the project both with RUP and with XP, we will think of our designs as executable programs. (Pretend that I'm going to scan in your UML drawings and UI screen mock-ups and press "execute", and that it will run just as your design describes.)

So, what you're delivering is "executable" software (as a design prototype in our case). Also the other part always expected when you deliver software: the official requirements. In addition, in this course you have to turn in one more piece of documentation: your project plan. This is to make sure you are actually getting experience planning a sizable project, rather than just hacking away and hoping for the best.

Requirements Document:

By the final version of the requirements, the content has probably changed from your original version. For example, if you are XP, you may have had to go back to your users to change the scope. So, expect change and track it, so that you can stay organized.

Here is what you need to have in your requirements document:

• The form of the requirements should follow the IEEE standard IEEE/ANSI 830-1998 given in Sommervile (pages 137-138 -- 7th and 8th eds.). Here is that standard structure:
• Section 1: Introduction -- short. Section 1.1 is purpose of the requirements document. Should be short, probably a paragraph. Section 1.2 should contain the paragraph describing your project vision (can be the same as you turned in for Homework #4). This will set the stage for the rest of the document. Section 1.3 (optional) contains any definitions, acronyms, or abbreviations you want to set up. Section 1.4 (optional) contains any reference documents, such as standard IEEE documents or whatever. (Section 1.5 will be omitted; normally it would be an overview of the rest of the document.)
• Section 2: will also be short. In here, put the characteristics of your target users and stakeholders. (This is shorter than the standard IEEE version of this section.)
• Section 3: The "main" part of the requirements will be in Section 3 of your requirements:
  • RUP: If you are RUP, Section 3 will be filled with Volere cards. Volere cards must be backed up appropriately (usually via use-cases and/or scenarios). Cross-reference to these (by number) in the "Event/Use Case #" field of your Volere card. (This is one way you ensure traceability of your requirements.)
  • XP: If you are XP, Section 3 will be filled with tasks, which you derived from your user stories. Tasks have to backed up by user stories.
• Appendix A: Put all your back-up materials relating to Section 3 in Appendix A. Be sure you use a numbering system on these materials, and refer to them explicitly by number in the section 3 requirements that relate to them.
• Appendix B: Put your Requirements Validations in Appendix B.
• Appendix C: If you delete a requirement, put it (cards or tasks with accompanying substantiation) in Appendix C. If you change a requirement put the old version in Appendix C.

In addition, as you make progress on your design, each fulfilled requirement needs to forward-reference the relevant sections in the Design document, which in turn refer back to the requirement, as a way of showing exactly how each requirement and design element relate. This helps accomplish both traceability and verification, because now you can make sure you didn't skip anything.

Additional notes for RUP:

• Pay careful attention to fit criteria, to make sure they are indeed clearly measurable and that it is obvious when they have been fulfilled. For example, if a requirement is "the system never crashes", it would not be appropriate for the fit criterion to also be "the system never crashes" -- because we cannot run the system until "never" in order to check off whether it has been met. (A reasonable fit criterion here might be: on the Windows platform, the system runs 100 consecutive hours of constant use involving at least 10 different users without crashing.) Thus, fit criteria ensure testability.
• There is a "History" place on the Volere card for recording changes. Use this to refer to previous versions of the card (in Appendix C).
• Scenarios (optional): Sometimes the most useful way to understand some aspect of how the system will be used is to write a scenario (much like a story) about it. Since a scenario is one path through a use case, this will lead to the development of use-cases.
• Use cases (required): Use cases are very important components of the RUP process, so don't neglect them in favor of scenarios. An example use-case was handed out in class. Although it is possible to start with a fuzzy use-case diagram that pretty much defines only the actors and the use-case name (there are some examples in the book like this), these are just early-stage use-cases. For this class, we'll write use cases textually, because that will help you make sure you're spelling things out all the way. By the time you turn in even the first version of your requirements document, use-cases need to be detailed and have outcomes. You are welcome develop some use-cases without developing scenarios first. Don't forget to label the "outcome" section of your use-cases.

XP: What is a user story?

It is not a list of features. Instead, these stories are written by users about what users can do and how the system's behavior looks to them. User stories have a sequence of events. They use vocabulary users know. We handed out a couple of examples. Here are three more examples, one invalid and two valid:

• NOT a user story: "There are 3 ways to protect against an authorized person logging in: passwords, ip verification, and fingerprint checking." Why this is not a user story: There is no user in it, and also there is no "story" (sequence of events). Further, it uses vocabulary a user would not be likely to know ("ip verification").
• Here is a user story: "To make the computer come alive, first I press my finger against a finger scanner. If I am authorized, I can then use the computer to attempt to access the secure database. It asks me for a password, and if I succeed in giving it a valid one, then it figures out if the computer I am sitting at is authorized to access that database. If all of these checks pass, then I can access the database."
• Here is another user story (Preece, p. 223): "This is where the admissions forms arrive. We receive about 50 a day during the peak application period. Brian here opens the forms and checks that they are complete, that is, that all the documentation has been included. You see, we require copies of relevant school exam results or evidence of work experience before we can process the application. If the application is complete, the forms get passed on to Susan."

XP: What should be done with user stories?

In XP, user stories get translated into development tasks. The tasks are your checklist of requirements. They belong in the requirements document.

In the finger scanning story, you have to figure out how you'll make the story come true in your software design, and that produces a list of tasks. You the technical person are writing these tasks, so you can use any technical details you want here. Obviously, this is no longer a story -- a technical list of things to accomplish is what you produce here.

XP: How many/how long?

As you can see from the examples, they are short. There are somewhere in the neighborhood of one/feature. However, if there are multiple situations possible for a feature that are non-obvious, you may need multiple stories for that feature. You can tell you have enough after you've passed your completeness check (recall that this is part of the Requirements Validation step; it will be part of your Appendix B).

Project Plan:

How are you going to get everything done? The plan needs to be something you are actually using to answer this question. It maps tasks to the calendar (via Gantt charts). It also assigns them to people. There are milestones and deadlines. All of these items need to be explicit in your written plan. Follow the outline given on pp 97-98 of Sommerville. Here is that outline, with some guidelines added:

1. Introduction: Very short. Describes objectives of the project and sets out contraints (number of personnel, time, etc.) that affect your project management decisions.
2. Project organization: Describes how your team is organized and the roles of the people on your team. You are allowed to just use your HW #3, if you are happy with it. Probable length: about a page or less.
3. Risk analysis: As has been stressed in class, this part of your planning should not be a work of fiction. What are your real risks in getting the work done? Do an in-depth risk analysis following the "Waltz" book's specifications. The results of your risk analysis are what belong in this section, in the format of the "Waltz" book's Appendix B's Risk Control Forms (downloadable copy is here, in case it's useful).
4. Hardware/software resource requirements: What hardware/software does your team (and ALSO next term's team, who will be doing the implementation) need to get the term project done? I would expect only about a paragraph here.
5. Work breakdown: Take your tasks and associate them with milestones and deliverables. Also make dependencies explicit. The format should be a table like this:

   Task	Duration (days)	Deliverables	Depends on
   Task 1: Meetings with clients and teams to gather user stories	3	User stories
   Milestone 1: We have all the initial user stories	N/A	N/A	N/A
   ...	...	...	...
   Milestone i: We have turned in REQ-1	N/A	N/A	N/A
   ...	...	...	...
   Task k: Detailed design as to how the generic XML parser should behave to accept all XML communications from the various modules	4	Specs for working parser	Tasks 4 and 6 plus Milestone 3
   ...	...	...	...

   • What are the tasks? Mostly, they are the ones listed in Section 3 of your requirements. These tasks actually need to be "implemented" (via UML). In addition, just like other software projects, preparation of project-related documents, testing, and any other non-coding tasks need to be factored into the task list too.
   • What are the deliverables? In your case, they are your assignments, and ultimately your final project. The correspondence to the real world is that, there too, you'd have to turn in a requirements document, a project plan, a design. There you would also turn in working software, but here we will pretend to scan in your design and push "run" -- the credibility of our being able to do that with your design document will help us decide if your software would really work.
   • What are the milestones? Deliverable hand-ins would be good ones, but this is just a suggestion. The final due-date shown on your plan for the "software" you are delivering is the same as the final due-date in the course, namely the last day of class.
   • RUP: How much of this needs to be figured out by when? If you are RUP, all of it is figured out up front (ie., by the time you turn in PP-1), but the beginning is detailed whereas the end will be fairly vague at first (since you haven't done much of your design yet). As your design work provides more and more information, you'll update this section of your plan.
   • XP: You roughly know how many releases and iterations you have, but you only do a detailed plan for the next iteration when the previous one is done. By the final hand-in though, it will all be scheduled out for XP as well.
6. Project schedule. Using the above, place the tasks along a time dimension. The format to use for this is Gantt charts (as in Pfleeger/Atlee Figure 3.6 (p. 93)). To get to this stage, starting out with activity graphs as in Pfleeger/Atlee Figure 3.2 (p. 86) may be helpful to you, but this is optional. The last date on your time line will be the due-date of the final project.
   • Assigning tasks to people: Obviously, for a project plan to have any relevance, it has to assign tasks to people. Make clear which team member is doing which tasks. (XP note: XP requires pair programming, which means pair UML diagramming in here. This means "programming" tasks will all require 2 people in your project plan.)
7. Monitoring mechanisms(data for process improvement): You need to be collecting data about your process, so that you can improve your planning process after each milestone.
   • A description of what you are monitoring, how you are monitoring it, and the actual data you collect from this monitoring goes here. As discussed in class, possibilities include counts of events, deadline near misses, grades received on early drafts, time spent on various tasks, etc. (Obviously, your team should use this data to solve problems and attend to risks that have become problems.)
   • Monitoring also includes risk transition monitoring -- watching for risk transition indicators that might arise. In this part, refer to the specific transition indicators on your Waltz cards, you are going to monitor.

Design:

The design is a collection of UML diagrams.

What to include:

The design is the "software" you are delivering, because we are pretending that it will try to execute when I scan it in. So, it needs to include information about the classes, their behavior, and how these things interact with what the user sees and does. Thus, the following components need to be included in your design document:

1. Architecture: What is the high-level architecture of how it's supposed to work? (You will develop your first attempt at this part in your Design-1ARCH assignment.)
2. The UI design: (You'll develop your first attempt at this part in your Design-1UI assignment.) Provide sketches of the UI screens and reports, with explicit ties to the classes and methods that update and take information from these UI components.
3. Class diagrams: There are 3 types of class information needed (is-a, has-a, and other relationships). Everyone's project needs to include class diagrams for every significant class and their relationships.
4. Behavior of the classes (methods): Specify every significant method's logic/behavior by sequence diagrams. (Optionally, you can also have activity diagrams and/or state charts, but these are in addition to sequence diagrams, not replacements for them.) There needs to be sufficient detail of these behaviors/methods and classes that it is clear how every requirement can indeed be met -- no handwaving.
5. Other: If there is anything else needed not included above, you should include it. For example, if your design includes dependency on third-party tools, you need to be explicit about exactly how your modules will communicate with those modules. Or, if your design includes a persistent database, then the way that database is structured and exactly how it relates to your software classes needs to be made explicit.

Organizational notes on your design document:

You may either organize it into sections labeled as per the above list, or else may organize it by "functionality" -- that is, first the first set of one or more related UI screens and the classes/methods that support it, then the second set, and so on.

All of the design documents need to refer back to requirements by number, so that it is clear exactly which requirements each design is taking care of. (This mirrors the forward references to the Design document you place in your Requirements document, which needs to refer forward to the pieces of the Design that implement each requirement.)

How many/how much detail?

You need a representation for each state the program can get into. ie, each screen, each type of database update, etc. And, you need to provide methods that get the program into/out of those states. And the classes that store those states. But, you do not need to provide designs of trivial helper methods or of trivial helper classes. For example, low-level methods such as traversing an array, string handling, constructors, methods to get or set a single field of an object, handling locks to protect multi-user access, generating random numbers, probability functions, and so on are not needed.

Note also that, naturally, every requirement needs to be covered by your design.

The ultimate test is whether you could hand this document to next term's team (made up of entirely different people) and they could then implement your design. If your design is not clear enough or complete enough to pass this test, it is not done yet.

Testing and Quality Assurance:

Your design needs to "work". How can you tell if it does? The person leading the QA effort on your team needs to give some serious thought to this. We have already talked about ways to validate the quality of the requirements. Some of the requirements validation steps may be usable for checking your design too. Walk-throughs/traces are also common ways to "test" code (here, diagrams) without using a computer. Also, be sure to check (and make explicit in the document) how thoroughly each of your requirements is covered in the design. (If you are using iRise, you can actually "run" your design, and that will be helpful toward your testing effort.)

When to do your QA work:

For RUP, testing is important and occurs throughout design and implementation, but the details of how to do it are up to you. For XP, there are specific requirements on the types of "testing" that you must do. Don't forget to do unit, integration, and acceptance "testing" of your design. Also don't forget that in XP, unit tests need to be designed before you start your diagram of that unit.