How to Write a Design Document

Overview

What goes into a design document?

A design document is a complete high-level solution to the problem presented. It should be detailed enough that somebody who already understands the problem could go out and code the project without having to make any significant decisions. Further, if this somebody happens to be an experienced coder, they should be able to use the design document to code the solution in a few hours (not necessarily including debugging).

So what actually goes in?

For example, this is the pseudocode I would write for the existing Condition::Wait:

void Condition::Wait()
   waiter = new Semaphore, initially 0
   append waiter to waitQueue
   conditionLock->Release()
   waiter->P()
   conditionLock->Acquire()

Your pseudocode has to be precise. For instance, in describing your solution for the Communicator class, it is not enough to say
   if anybody's waiting, then signal cv
You need to say how you determine if anybody's waiting, e.g. by saying
   if (waitingReceivers>0 or waitingSenders>0) then signal cv

What doesn't go into a design document?

Keep in mind that your TA understands the project very well. Do not restate the problem in your design document. Your TA is far more interested in your solution than in knowing that you understood the problem.

Another important thing to remember is that a design document is not a test case document. If you want, you may itemize things that will need testing, but do not actually state your test cases in your design document. Test cases are really boring to read, and we have to read around 13 or so design documents per project.

Also, your design document should contain very little actual code, if any at all. Include psuedocode for all complex procedures, but do not include C/C++ code.

The purpose of pseudocode is to avoid all the annoying aspects of programming languages that make code both harder to write and harder to read. The purpose of pseudocode is not to be imprecise about how you solve a problem. Comments are welcome, but ASSERT and DEBUG statements, for example, do not belong in pseudocode.

Remember that we have to read your design documents. If you don't think we want to see it, don't put it in!

How do I convert x to postscript?

Be sure to make sure your .ps file works before you turn it in (try viewing it with gs or gsview).

How do I submit a design document?

Place your design in a file called projN-design.ps, where N is the project number. For project 1, your design document should be called proj1-design.ps. Make sure you can view this file in a Ghostscript viewer (try gs on instructional machines, or gsview in Windows).

Now, in the directory containing projN-design.ps, run

  submit projN-design
again, subtituting the project number for N. For project 1, you would type
  submit proj1-design