COS 333 Project Design Document

Due midnight, Friday, March 12

Fri Feb 19 09:58:26 EST 2010

The purpose of a design document is to encourage you to do some detailed thinking about what your project is, and how you're going to work on it over the next 10-11 weeks. The more thinking you do ahead of time, the easier the pieces will come together when you do start to implement. Implementation before design is not a good idea.

The design document should be resonably close to this form and roughly double this size, that is, 3-4 pages. You can use ASCII or Word or something else if you prefer it to HTML. There's no need for fancy graphics or strong production values -- the content is what counts, though a reasonable level of detail, perhaps some diagrams and screenshots, and good English free of typos and spelling mistakes will help suggest that you have taken some care with it.

This link points to a good design document from a couple of years ago, used with permission.

Submit your document with this Dropbox link.

Identification:

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

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 likely organization and operating environment: for example, a web-based application with Ajax in the browser and PHP on a Linux server, or an iPhone app that accesses a remote server.

Scenarios:

This section should give two or three scenarios, perhaps a couple of paragraphs each, of what a typical user of your system would do in a typical session. If you work through some scenarios carefully, the rest of the system will be a lot easier. Joel Spolsky's articles on functional specifications are worth reading. You don't need as much detail as he suggests but the kind of thinking behind it is very helpful. In particular, figuring out the main screens of the user interface will help organize your system.

For example, if you were doing a new version of Point, how would you describe two or three typical sequences of interactions, including what the user would see and do for each? If you were building an iPhone app, what would be the three or four screens and what controls would be on each one?

Focus on this part before you worry about implementation languages and the like; until you know what you're going to build, it may be premature to worry about languages and tools, though those do affect what you can actually accomplish and for some things there's no choice anyway.

Architecture:

A brief description of the major components, what they do, how they connect and interact, and the most likely implementation. This is roughly what Spolsky calls a technical specification.

One major component will be 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 take? For example, it might be written with Flash to provide something graphically sophisticated, or it might use Ajax to provide rapid response, or it might be vanilla HTML. Which seems most likely?

Another component is likely to be a database where information is stored and subsequently retrieved. What information is stored in the database? What is the source of the data? Is there more than one source, as in a mashup? What are the basic relational tables likely to be? Does your system require an administrative interface to manage things like user accounts and bulk database updates? Some frameworks like Django create an admin interface for you -- is this an option?

A typical 3-tier system will have logic in the middle that extracts query requests from forms, builds database queries, and formats the results. This processing is the most specific to your project, so you want to plan it and spell it out carefully. 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?

Describe interfaces between components, at least at a high level: what information passes in each direction, in what format, and what the major interfaces will look like. Interfaces insulate each part of the system from details of the 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 (e.g., Postgres or SQLite) without much change, and you could make major changes to the database tables without affecting much of the rest of your system. 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 or retrieves information from the database.

Include a brief discussion of the likely implementation choices: languages and tools for various parts, operating environments for servers and clients, choice of database system, code repository, and the like. None of this is binding, but you should have thought seriously about it.

Milestones:

Include a list of significant milestones that you plan to have achieved 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 running perfectly by Dean's Date.

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

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? Plan for a sequence of stages where you can stop at any time and declare success.

This timeline from a previous project tells how a well-run project progressed; you might study that as you think about your own schedule. You will have to maintain your own timeline, so plan to start soon.

Risks and Open Issues:

This is the place to show that you've thought about what you need to do 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 brand 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 Python, 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? Where will your SVN repository be stored? Do you need a CS account? Do Java programs work with campuscgi? Can you test iPhone applications without a real phone? Do you need a developer certificate? Where are you going to host your system? Do you need web hosting and your own domain? 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. This is especially true for any aspect that depends on anyone or anything outside your group.

Help is available:

As always, the TAs and I are happy to discuss any aspects of your project at any time, but this works best early in the process.