These documents are intended to take the mystery out of the milestone deliverables for CMPS 115. We'll always be available to help you - in class, via email, and during office hours as well as scheduled meeting times, but sometimes it's just nice to have an example - hence these documents.
There are five deliverable milestones:
1. The System Requirements Document
2. The System User Manual
3. Design Documentation, parts 1 and 2
4. Your game code and a coding standard
5. A Test Procedure and Report
For each milestone we've provided an example and a grading/inspection sheet. For the documents where it's important that certain information be present and the information is where we expect it to be, we've included templates. The templates are available in both HTML and in MS Word 97 formats. For the *nix-heads, the Word documents can be used in Star Office, which you can download from the Sun web site, and in AbiWord, which you can download from the AbiSource web site. Both packages are free.
For the System Requirements Document (SRD), we've also included an annotated template and guidelines for how to write a requirement. Requirements seem to be the most mysterious part of the class and they are also the most important, in the sense that you're requirements set the basis for your grade. Therefore, there's a lot in here about those.
Some Questions You Might be Asking Yourself
There are a zillion different design methodologies,
many of them expressly designed for certain types of projects (real time
systems, financial applications, etc). Our goal in this class is to introduce
you to some of the documents most commonly used industry wide, in hopes
that you'll understand enough when you actually go to work so that you
can figure out what you need to ask about their process.
Will I really have to do stuff like this in the real world?
In short, yes. There are lots of contributing reasons, but the fundamental one is that software exists over time. This is obvious when you consider that up to 90% of all software costs are in maintenance - when you invest in an expensive payroll application, you don't want to buy a new one every year. Subtler is that the design and implementation take place over time - we wouldn't need a lot of this stuff if you could instantly implement your code. Here's a classic scenarios to illustrate this point:
You're on the phone chatting with your customer counterpart about some functionality she'd like to get. Suddenly, you have a wonderful idea and you tell her about it. She's thrilled. You go off to flesh out the design and she goes off to get you money to pay for it.
You go to talk to your boss about it and he asks if you could add a few fields to the query page so that it would work for another customer. The two of you agree, but while you're thinking about it, you realize that in order for those fields to be filled out properly, the user has to have access to a database, so you add that in. This is getting cool.
Meanwhile, your customer talks to her boss and he wants to field it as an applet that they can run on their intranet web site. You customer thinks that's a great idea and gets money to develop a stripped down little applet that they think can save 5% of their HR people's time. In two weeks, she calls you and asks, "When can you deliver?" You get angry - you have 12 UI screens to build, a database connection, and the processing to drive them. She gets angry - you told her you could crank it out in a couple of days, even with some lightweight documentation AND it's an application, not an applet.
What went wrong? You didn't write down what you agreed
to with your customer and your visions of the program changed over time.
That isn't unusual. What documentation does is make you conscious of the
decisions you make.
Will the game we build be the most over documented program in history?
No, you will have trouble achieving the levels set
by your peers who preceded you through this class. They built the
most over documented apps in history.
How much time is this entire project going to take us?
Probably a lot longer than you think, which is definately longer than it has to take... (Think about that one for a minute.) Keep in mind that there is no extra reward for extra work in this class. The only truly original document you'll be doing is the Requirements Document. After that, you steal as much as you can from the preceding document for the one you're working on currently. It really pays to look ahead and see if there's a way to do your work now in such a way that it will save you time later. We'll try to alert you to these things, and the examples illustrate it pretty clearly.