Due midnight, Friday, March 14
Thu Mar 6 19:20:51 EST 2014
Updated to clarify the timeline requirement.
The purpose of the Project Design Document is to encourage you to do 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.
The Project Design Document should sketch out what you expect to accomplish in your project, and how. This should include an overview of what your system will do, the basic organization and components, and a rough schedule of what you expect to accomplish each week or two. It should identify any significant risk factors and what you will do if bad things happen. ("We're expecting a large donation to buy a server; we will drop the course if this doesn't come through in time.") None of these are binding commitments, but the more thought you put into up-front planning, the more likely that things will work out well.
The document should be reasonably close to this form and about 3-4 pages printed pages long. There's no need for fancy graphics or strong production values -- the content is what counts, although a reasonable level of detail, perhaps some diagrams and screenshots, and good English free of typos and spelling mistakes will suggest that you have taken some care with it.
Here are three good design documents from a couple of years ago, all of which led to excellent projects: one, two, three.
Submit your PDF or HTML document to the dropbox link https://dropbox.cs.princeton.edu/COS333_S2014/designdoc by March 14.
The document should include these components.
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 a phone app, what would be the three or four main screens and what controls would be on each one?
Focus on this part before you worry too much about implementation languages and the like; until you know what you're going to build, it may be premature to focus on languages and tools, though those do affect what you can actually accomplish and for some things there's no choice anyway.
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, would you likely use tools like Bootstrap and jQuery, or try to roll your own?
Another component is 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 tables likely to be? Should you use a NoSQL database instead of a relational one? 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.
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 AppEngine 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.
For example, if only one of you knows Python, while two know PHP 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. Where will your SVN or Git repository be stored? Can you test iPhone applications without a real phone? For that matter, can you develop iPhone apps without a Mac? (Answer: not really.) Do you need a developer certificate? (We can probably help.)
Where are you going to host your system? The usual suspects -- OIT, Heroku, AppEngine, AWS -- all have pros and cons, and you want to think about this early. Do you want to get your own domain?
Crucially, if you will rely on the availability of some data set, you have to make sure it's really available now; if not, that's a major problem. 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.
You have to maintain a timeline for your project, in HTML, that provides a contemporaneous record of what you are doing. Post this on your project web page, and we will provide a page of all the links for all the projects, so you can see how others are doing, and with luck be able to offer each other help and share insights. This timeline from a previous project (which implemented a web version of the game Settlers of Catan) tells how a well-run project progressed; you might study that as you think about your own schedule.
You should be updating the timeline at least two or three times a week, as things happen, and review it with your TA during each weekly status meeting. It would be good if your timeline included some indication of what you plan to do next at each stage; that makes it easier to see whether you are meeting your short-terms goals.
None of this has to be very long or detailed, but it has to be done as you go along, not after the fact.