CSCI 265 Project Design document

As a general rule, all documents should adhere to high standards of writing quality, including spell checking, grammatical correctness, consistent layouts/formats, appropriate use of footnotes, appendices, glossaries, tables/figures/diagrams, citations, etc.

We want to ensure a clear, clean design has been documented in a single shared resource (the design.md file).

This will be a large and fundamental document for the project, and involves documenting in detail both the logical and physical design of the product.

The document is the one your team (and the instructor and other readers) will/would be using as a reference point when working on or revising the product implementation, so needs to be well organized, consistent, and as complete, up to date, and error free as possible.

The actual format of the document is left largely to the team's discretion, but discussion of the expected content is provided below, and the lecture material covers a variety of ideas and approaches to design modeling.

However the document is actually structured/ordered, the following information (at a minimum) needs to be present:

The team and project name, contact info (the contact info is just a single point of contact in case a reader has questions or feedback)
A table of contents (optional but nice to have)
A design overview
This provides an intuitive overview of the high level logical design, preferably with a context diagram (the top level DFD), and also of the key transformations/decisions that will be needed when going from the logical design to an implementation.

The logical design
In the logical design we need to specify the decomposition of our system into smaller components from a logical (code-independent) perspective. The logical design should reflect either a layered/top-down approach or an object-oriented approach (or a hybrid of the two), clearly describing the division of the overall system into key components, then clearly describing the decomposition of those, etc. as needed.

A medium-sized project might involve dividing the overall system into several interacting subsystems, dividing each subsystem into several interacting modules, dividing each module into a number of interacting components, etc.

Since different subsystems/modules/components will likely be developed by different people, it is important that as a team we clearly establish the responsibilities of each element and how they will interact with others. Thus for each level of decomposition I generally recommend the inclusion of a data flow diagram (DFD), with clear supporting explanation.

Each element of the system (i.e. each subsystem, module, component, etc) should contain clear, easily referenced descriptions of:

its overall purpose
each of the services it provides for other elements of the same DFD level (what will it implement that is used by other portions of the system?)
- this should show the information exchanged during that process
the interactions between it and the user(s) and any other external systems
any persistent data it will need to store, giving each data component a name and identifying the type and restrictions on the data (e.g. "vehicle weight will be stored as a non-negative real number of kilos, rounded to the nearest kilo)

As discussed in lectures, we are seeking a division into elements that are cohesive yet loosely coupled, and we want to ensure that all aspects of the overall product functionality are captured somewhere within our design.

Note on the modeling/diagrams aspects:
After the re-scheduling due to the instructor absence, the various diagramming techniques (DFDs, ERDs, activity diagrams, state diagrams, sequence diagrams) probably won't get covered in class until the 14th. The deadline for the phase 3 documentation has been moved to the 21st, so hopefully you'll have time to complete the needed diagrams by then, but I'm not expecting much in terms of diagrams for the in-lab presentations, especially for the teams presenting on the 16th.

Preliminary thoughts on the transition from the logical design to an implementation
Eventually we'll need to map the elements of our logical design to actual codable entities.
This section isn't expected to be rigorously completed for phase 3, but the goal is to have an organized start/outline (something we can build off of in phase 4 to get implementation underway).
Key elements to consider include:
- identifying the programming language(s) and any supporting tools to be used
- identifying the directory and file naming structure to be used within the code repository: identifying the files/directories/subdirectories we use to store the different actual code elements
- identifying the implementation method for each shared data store (database, file, etc), including format, fields, layout
- identifying the interface for all public services provided by the element:
  - publicly accessible/shared data types and fixed/constant values
  - publicly callable routines, what they return, what they'll expect as parameters
  - classes/objects to be used, their key public fields and methods
  This gets close to the level of code skeletons, but does not yet need to be expressed as actual code in the target language(s).
A glossary: This is optional but often nice to have: if a term is specific to the product or is unlikely to be known by the average reader (e.g. a random second year CS student) then include an entry for it.
Any appendices (if/as needed)

Note that all elements of all figures/diagrams should be clearly described/referenced in the associated text.