Due: document by Monday, Feb 01, 2016, 23:00 Due: slides by Tuesday, Feb 02, 2016, 23:00
You have already worked to define a system you will deliver by the end of the quarter. The purpose of this team assignment is to accomplish the detailed architectural design and phased product delivery plan for your system, before you implement your ideas in code. A common name for this document is a System Design Specification (SDS), although in our case, we are augmenting the design with planning components. Among other things, your SDS should answer the questions: what are your modules (packages, classes, or other units of abstraction), what are the responsibilities of each module, and how do the modules interact/collaborate?
Note that the SDS will be a living document. You will update it periodically during the development cycle. As part of developing the SDS, you may need to revise your SRS. Keeping these documents up to date with changes as they happen will make it easier to keep your team and customers in sync, and to meet your later deliverables.
After you complete your SDS, you will present it to your customers (during class), convincing them that:
Thus, there are two deliverables, with two different deadlines: a document and slides for a presentation. Both document and the slides must be in PDF format.
In evaluating your work, we will be looking to see that you have addressed all the necessary elements of an architecture, covered well the planning material described above, and made reasonable decisions related to all project components.
Your document should include an architecture section and a process section.
The System Architecture document provides a detailed definition of the system’s software components. It identifies the major modules and their functionality, and the interfaces between modules, required to implement the system. It should address the design of the system from the customer's viewpoint, as well as that of the developer or administrator. (This may require separate perspectives and/or diagrams.)
Describe, in detail, what data your system stores, and how. If it uses a database, give the high level database schema. If not, describe how you are storing the data and its organization.
For two design decisions for which you seriously considered an alternative, briefly describe that alternative. Discuss its pros and cons and why you chose the design you did.
If there are particular assumptions in your design, identify them.
You (and more especially your readers!) may find it useful to first create a customer view of the system (at a high level of abstraction) and/or a UML class/dependence diagram of the modules of the system.
For full points, the architecture section must include at least two views of the system architecture, with one view being a UML class diagram. You also must include two UML sequence diagrams outlining two of the use cases from your SRS.
The software tools section of the project webpage lists some tools you can use for drawing UML diagrams.
The UML class diagram must include all major classes and enough detail to both answer questions about the design, and to let design be critiqued.
Your diagram should display
all major classes, attributes (fields), methods (do not list get/set/is methods), inheritance/interface relationships, and
associational relationships (named and directed, with multiplicity annotations).
If you are listing classes in your class diagram, take care not to forget important classes that would reasonably be needed to solve the task you are working on. Do not forget to include classes for all aspects of your system, such as user interface, data modeling, database interaction, any “helper” classes or utility code, etc. In the past, some groups have focused too much on user interface classes and have done a poor job capturing the details of the “model” of your system, the classes that actually represent the important data and behavior necessary for the task.
The UML sequence diagrams should depict your product executing two of its important use cases. These can be the same use cases you wrote about in your requirements document (SRS). The sequence diagrams show the “life” of a user's interaction with the system (e.g., web request). Your diagram should show all participants (objects) in the sequence, all important directed messages between them, and their return values (if any). Show the request's path as it interacts with each part of your system to accomplish the task. Take care not to omit important steps or details. Make sure that the state of the system at the end of the path through the diagram matches the expectations from the use case to which it relates.
Use good design with decentralized control. Choose a flow of control that is reasonable for your type of project and the goal being achieved in the scenario. Ideally no one class or object should do too large a share of the work to complete the scenario.
Your design should use the design principles discussed in this class and prior ones. Here are some general design tips, which essentially come down to “put functionality in a logical place”.
The process section of your document should address 6 topics, described below.
Identify the top five risks to successful completion of your project. For each, give:
Explicitly state how this has changed since the SRS.
When deciding which 5 risks to include, you can informally multiply the likelihood by the impact to determine the importance of a given risk. You should pay attention to risks in proportion to their importance. Don't belabor low-likelihood, low-impact risks.
Identify milestones (external and internal), define tasks along with effort estimates (at granularity no coarser than 1-person-week units), and identify dependences among them. (What has to be complete before you can begin implementing component X? What has to be complete before you can start testing component X? What has to be complete before you can run an entire (small) use case?) This should reflect your actual plan of work, possibly including items your team has already completed. Consult your SRS Feature List for input.
To build a schedule, start with your major milestones (tend to be noun-like) and fill in the tasks (tend to start with a verb) that will allow you to achieve them. A simple table or spreadsheet is fine for this size of a project.
Describe your team structure (how you have organized the team, what are members' roles and responsibilities), elaborate on milestones (external and internal), define tasks, and specify the team member responsible for each task. This should reflect your actual plan of work, including items your team may have already completed. You may find yourself revisiting your organization during the lifecycle of the project. Describe the way your team will communicate, for example: date/time of weekly meeting, location of weekly status reports, wiki, email alias.
Describe what aspects you plan to test and why they are sufficient, as well as how specifically you plan to test those aspects in a disciplined way. Discuss unit test, system (integration) test, and usability test strategy, along with any specific test suites identified to capture the requirements (SRS). Identify the mechanism that you will use to track bugs that occur during use and testing. (For a large project, use of a specialized bug tracking tool is critical. For this project, we do not require it, but we strongly recommend it. Whatever you use must be kept up to date and visible to the course staff.)
We will not have covered this material in class by the time the SDS is due. Do your best and plan to revisit this section during a later phase of the lifecycle. Below is a sample structure for the section.
Define the documentation that you plan to deliver with the system, e.g., user guides, admin guides, man pages, help menus.
For each programming language that you will use in the implementation of your project, provide a link to a pre-existing coding style guideline that the members of your project will follow. Do not try to make up your own guidelines.
Briefly state how you plan to enforce these guidelines.
Submit slides in PDF format for a 10-minute presentation that convinces your customer that you are on track for successful delivery of a worthwhile project. Each 10-minute presentation will be followed by a 3-minute Q&A session with the audience.
Your presentation should summarize the requirements (the project's purpose, what is novel about it, its UI and major features), its architectural design, and your planning for the implementation. You can't give all details about any of these; focus on what is most interesting, novel, risky, etc. 8-10 slides are typically appropriate for a 10-minute presentation, but you may use as many or as few as you think will be effective.
A good presentation will contain more slides with a diagram than without. Diagrams can be taken directly from your other documents, if appropriate, but you may find that the different format requires different drawings in some cases.
Exactly 3 group members must participate in the presentation. Different members will participate in future presentations. Don't go over 9-10 minutes; it is better to leave more time for questions than to fill your slot and deny the audience the chance to better understand your work.
Be brief! We have listed quite a few types of information that is useful. However, many of these items can be concisely addressed. The point of a document is to convey information, and the longer your document is, the less chance someone has of reading the document and/or finding the information they want in it. (Also, your TA will thank you for being brief.)
Do not include content-free filler in your documents or presentations. This includes anything that could appear in identical form in another group's materials. For example, don't merely state as a risk, “we might fall behind schedule” (another example is “we don't know the tools”). Of course you might—so might anyone. What factors do you think are most likely to cause schedule slippage for your project? Why do you think those are the parts of the schedule with the greatest potential variance? What have you done, or what do you plan to do, to learn more about how long those particular tasks will really take?
When you create a class diagram, put every class into a module. For example, if you are using the Model-View-Controller architecture, then your class diagram should also reflect this. Create three regions in your class diagram (use colors or bigger boxes that contain the classes, and put each class in the relevant port of your class diagram).
See Michael Ernst's hints on giving a technical presentation, and the hints for the proposal presentation.
Remind the audience of your goal, and especially of differentiating factors that make your project better than existing approaches to the problem.
Any description of your project, its goals, and what it does must include a picture (possibly multiple pictures) of its UI. When discussing the UI picture, don't just enumerate the components to the audience. Rather, discuss how a user performs some task using the UI.
There is no need to give a list of 20 development milestones. It's more important, especially in a talk where time (and audience attention) are limited, to focus on larger blocks. But even a list of 6 tasks (with dates) is not very interesting. It's more important to show the dependences among them, to make clear that the schedule is achievable. Your schedule must contain concrete deliverables; it is useless to just repeat the class due dates without saying what you plan to do at each step.
Do not present a sequence diagram, class diagram, or any other material just because it is there. Rather, ask yourself whether this is important and what key point it is bringing across. For example, it might indicate some key feature of your design, or how the parts of your system work together. The point is not to give a long list of procedure names, but to develop insight that would let someone else generate that list.
Class diagrams presented in a talk should usually be simpler than those in a document. For example, you don't have time to go over all the procedure names, so you should elide them unless there is a compelling reason otherwise. Your diagrams must not use unreadably small writing. Be willing to redraw your diagrams for the presentation.
Practice the presentation before you turn it in.