Project 2: Design Document
Draft Version Due by: Friday, October 11, 2024 at 11:59 p.m.
Final Version Due by: Monday, October 21, 2024 at 11:59 p.m.
Introduction
The design document for your software project is intended to guide the implementation phase. While your requirements document specified the what, your design document should specify the how, breaking down your large project into manageable pieces that interoperate in a clear way.
The goal of this phase is to make all the important decisions for your software: visual interface, communication, data storage, and so on. Programmers should not need to stop and make these decisions as they code; instead, they should be able to look at the appropriate section of the design document and implement the decision made there. If you don't know what your system will look like or how it will behave when you start the next phase, you've left something out of this design document.
Note: diagrams.net offers a free, cloud-based platform for drawing many kinds of diagrams, including UML diagrams.
The submission for your design document must contain technical writing, diagrams, and working code, broken down into the following elements.
Elements
Introduction
Briefly, describe the purpose of the design document and its intended audience. Then, describe the scope of your software. This description may be similar or identical to statements from your software requirements specification. End the introduction with a short overview of the rest of the document.
System Architecture
Include at least one block diagram and any necessary text to describe the overarching organization of your system. It may be appropriate to make tentative assignments of team members to each component in your architecture.
Describe your system or at least some part of your system using at least one of the following architectural patterns.
- Model-View-Controller
- Client-Server Architecture
- Layered Architecture
- Pipe and Filter Architecture
- Repository Architecture
You are encouraged to use sequence diagrams or state diagrams to describe the functioning of your system or communication that occurs within it.
Data Design
Describe the data structures you will use to store data in your program.
If your program has a networked component, explain what kinds of data will be sent under what circumstances. You may want to include a sequence diagram.
If your program reads or writes files, explain where this data comes from, where it goes to, and how it's formatted.
Component Design
Design the classes and objects in your system. These objects should be presented in at least one UML class diagram, showing relationships between them.
Ideally, both members and methods will be listed for each object, though elements at this level of detail will likely change during implementation.
When possible, identify classes as following a specific, named design pattern.
Interface Design
What will your application look like? Draw wireframes showing the basic layout of all the elements of your GUI components. If you have several different screens, draw a wireframe for each one. Annotate each wireframe with information about enabling and disabling buttons and other UI elements that change. If the changes are complex enough, create a different wireframe for each state.
If you have different kinds of users interacting with your system, include a use case diagram.
If your system transitions to different states, include one or more state diagrams.
Prototype
You must include a prototype (working code) of some element of your system you want to test out. Ideally, this prototype will help you clarify some aspect of your system and make further design and implementation decisions.
You should probably check with me to make sure that your prototype is reasonable, but all of your projects have a GUI, and that might be a good place to start as it will help you make your feature list more concrete.
It is perfectly reasonably to have several prototypes that explore different options. The prototypes do not need to be fully usable and may have portions that are non-functional or incomplete. The key is making something useful for your future development process. A larger prototype is better than a smaller one because it's smart to get a head start on all the coding you'll need to do.
Milestones
Include a list of milestones describing major features and the dates when they'll be completed. Each milestone should list all of the functional requirements that should be implemented by the milestone. Using Friday work days as deadlines is a reasonable approach. You will not be required to meet your milestones exactly, but they will give you a sense of the progress of your project. Be as detailed as possible. Take time to work out which features are dependent on other features so that you can make a logical plan for completing the project. Assign people to particular tasks even though some flexibility for who works on what might be required later. Make a Gantt chart showing the features and how they fit the timeline.
Your milestones should plan for core features to be implemented by the deadline for Project 3. The time after Project 3 is reserved for testing, stretch goals, documentation, and finishing features that took longer than you expected. Planning to add core features up until the last day of the semester is a recipe for disaster.
Resources
Software design documents will all look different. Each software system has its own architecture, interfaces, and data design. For that reason, it's difficult to provide you with examples of design documents that will look much like the ones you will create, but the following resources give some insights and guidelines about how to make a design document:
- How To Write Software Design Documents
- Blog post, "Why Writing Software Design Documents Matters"
- Example software design document
Submission
Commit your Word, PDF, or LaTeX files and Java source files to the private GitHub repository for your group. As in the previous project, you should commit your design documents by copying them into a folder called docs in your IntelliJ project. Name the design document Design.docx or similar. The document should include information about which source files are included in the prototype. Create separate tagged releases with the names Draft Design and Final Design for the draft and final versions, respectively. Doing so marks the state of your repository at those points.
The draft version of the documents and prototype must be submitted by Friday, October 11, 2024 at 11:59 p.m. I will grade and give feedback on these materials over the weekend and return them to you by Monday.
The final version of the documents and prototype must be submitted by Monday, October 21, 2024 at 11:59 p.m. The final version will be graded based on the same standards as the draft document, with an extra grading category for how effectively feedback on the draft has been incorporated.
All work must be done within assigned teams. You may discuss general concepts with your classmates, but it's never acceptable for you to look at another team's code. Please refer to the course policies if you have any questions about academic integrity. If you have trouble with the assignment, I am always available for assistance.
Grading
Your grade will be determined by the following categories:
| Category | Draft Weight | Final Weight |
|---|---|---|
| Introduction | 5% | 4% |
| System Architecture | 10% | 8% |
| Data Design | 5% | 4% |
| Component Design | 15% | 12% |
| Interface Design | 20% | 16% |
| Prototype | 20% | 16% |
| Milestones | 15% | 12% |
| Spelling, grammar, style, and formatting | 10% | 8% |
| Incorporation of feedback from draft document | 20% |
