Software Design Specification

Due: SDS documents & slides at 23:00 on October 21, 2016 via course dropbox
Due: in-class presentation at 10:30-11:20 on October 24, 2016 in SMI 304
Due: in-class presentation at 10:30-11:20 on October 26, 2016 in SMI 304

Overview

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 the staff in sync, and to meet your later deliverables.

After you complete your SDS, you will present it in class, convincing the staff and your classmates that:

Deliverables

There are two deliverables for this assignment: your design document and slides for the in-class 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.

Design document

Your document should include an architecture section and a process section.

System architecture

The architecture section should provide 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.

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 compared to your design choice.

If there are particular assumptions in your design, identify them.

Diagrams

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.

Class 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 methods), inheritance/interface relationships, and associational relationships (named and directed, with multiplicity annotations).

Include classes for all aspects of your system, such as user interface, data modeling, database interaction, etc. In the past, some groups have focused too much on user interface classes and have done a poor job capturing the “model” of your system—the classes that actually represent the important data and behavior necessary for the task.

Sequence diagrams

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. 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.

Design tips

Your design should use the principles discussed in this course and prior ones:

Process

The process section of your document should address 6 topics, described below.

Risk assessment

Identify the top five risks to successful completion of your project. For each, give:

Explicitly state how this has changed since the SRS.

Project schedule

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.

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.

Team structure

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, mailing list, etc.

Test plan

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). We require that you use GitHub Issues to track bugs that occur during use and testing.

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.

Documentation plan

Define the documentation that you plan to deliver with the system, e.g., user guides, admin guides, man pages, help menus.

Coding style guidelines

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.

Design presentation

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 2-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.

Hints

Document hints

Be brief. Your documents should addressed the required points briefly and clearly. The staff will deduct points for overly long, poorly organized, or poorly explained documents.

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”). 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?

Your class diagram should reflect your choice of architecture. For example, if you are using the Model-View-Controller architecture, your diagram should make it clear which classes implement the model, the view, and the controller of your system.

Presentation hits

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 one or more pictures of its UI. When discussing a UI picture, don’t just enumerate the components to the audience. Rather, discuss how a user performs some task using the UI.

When presenting your process and development plan, focus on making it clear that your proposed schedule is achievable. Your schedule must contain concrete deliverables.

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. The text in your diagrams must be readable. Be prepared to redraw your diagrams for the presentation.

Practice the presentation.