COS 333 Project Design Document

Tue Feb 22 10:10:29 EST 2005

The purpose of requiring a design document is to encourage you to think seriously about what your project is, and how you're going to work on it over the next 11 weeks. As discussed briefly in class, the more effort you put into thinking about things ahead of time, the easier they will just come together when you do start to implement. Implementation followed by design is not a good idea.

The design document should be more or less in this form, though you can use ASCII or Word if you prefer. There's no need for fancy graphics or strong production values. The content is what counts, though good English and the absence of typos and spelling mistakes will suggest that you have taken some care with it.
 

Identification

Project name, group member names and email addresses, project manager, URL.

Overview

A few sentences that tell what your project is, what it hopes to accomplish and the like; the first sentence or two should tell the main story. A second paragraph might list the major features. It might also compare and contrast your system if it is like some existing system. A third paragraph might spell out the basic organization and operating environment: for example, a web-based application with Flash in the browser and a Linux server.

Components

The bulk of the content will be in this section and the next, which may be combined into a single Architecture section if it seems more natural. This will give a brief description of the major components, what they do, and the most likely implementation. It might also say which team members will be mainly responsible for which parts, though that's not necessary.

For example, one component is likely to be a database where information about client visits is recorded. It would make it possible to recall previous visits by this client and make information from those visits accessible for searching and combining with the current query. What information is stored in the database? Is there more than one database? What are the basic relational tables?

Another component will the the user interface. Web users might see a GUI that lets them search for information, select parts of it for update, and see the updated information. What form will this interface likely take? For example, it might be written with Flash to provide something very graphically sophisticated. In that case, would you need another component to provide the same information for users who do not have Flash?

If your system requires some kind of administrative interface, that would likely be another component; you would want to discuss its properties as well, and perhaps say what you plan to do about security issues, if anything.

A typical 3-tier system will have logic in the middle that extracts query requests from forms, formulates database queries, and formats the return information. This processing is the most specific to your project, so you want to plan it and spell it out as carefully as you can here. What kinds of information are presented to the user, what responses are received, what processing is done on those before something is sent back to the user?

Interfaces

This should describe how the components communicate with each other, at least at a high level: what information passes in each direction, in what format, and what the major interfaces will look like. The critical issue with interfaces is that they insulate one part of the system from details of other parts.

For example, you should specify interfaces to the database in such a way that you could reasonably replace one database system (say MySQL) by another (Postgres) without change. Similarly, you should be able to make significant changes to the user interface appearance without changing the code that processes the information from the user.

Milestones

You must include a list of significant milestones that you plan to have working or accomplished roughly every week or two until the end. Allow for slippage, and for all the required components at the end: preparation of a talk and demo; documentation and other writeups; submission package; working version for grading.

What's a milestone? Basically, it's some task or feature or the like that is either 100% done, or not, and you only count it as met when it is 100% done. So installing a web server on a personal machine or shipping a beta version to a friend to try is a milestone, but "coding done" is not, since you don't know what "done" means.

What are the stages of your delivery? What will you build first to demonstrate minimal but working end to end functionality? What do you plan to have working for your first prototype?

The timeline for a previous project tells how a very well-run project progressed; you might study that as you think about your own schedule.

Risks

This is the place to show that you've thought about what you need and what might go wrong or cause delay. We're not interested in generic risks like someone getting sick or the dog eating your hard drive, but in perils specific to your project. Do you need to learn a new language or tool or system? Are you dependent on getting data or software or hardware or access to a particular system? What will you do if your preferred path is blocked? It's important to give this some thought, so you don't discover a month from now that you simply can't do something that you were counting on.

For example, if you plan to use Flash, do you have to acquire a copy somewhere, and does it cost money? If only one of you knows PHP, while two know Java but not well, there's a potential problem either way, and you have to assess which path to follow and allow some time for getting up to speed. Do PHP and MySQL run on OIT machines? Do Java programs work with campuscgi? You should find out right away whether your intended software is available on your intended platforms, and have a fallback plan if it is not.

Help is available

As always, the TAs and I are happy to discuss any aspects of your project at any time.