Design Documentation

General

Design documents serve two purposes.  First, they aid others who may have
an interest in the program.  Your instructor, manager, co-workers, or even 
you yourself, should be able look over these documents to determine how 
your program is organized and for what purpose.  Why would *you* need these
documents?  So that next month or next year, when you are required to 
add a feature or rewrite a section of the code, you can easily understand 
how the program is organized allowing you to quickly make the required 
changes.

The second purpose for design documents involves you also.  In order to 
solve anything more than the simplest of problems, you have to understand 
the problem and review the details of the solution to be sure you have the 
correct solution (and the correct problem!).  Many times you will sit down 
to write a program or begin a project and the solution exists only in your 
mind.  For most problems and for most of us, this is not good enough. Without 
writing anything down, we can only focus on one part of the problem at any 
one point in time.  We can only get a vague feeling as to how the pieces fit 
together. To understand the problem and to be sure you have a viable solution, 
you need to sketch out at least a few details, including a statement of the 
problem, information on all of the input, information on all of the output, 
a function call diagram, and pseudocode for each expected function.

These are the minimum areas you should consider before starting a project or 
program.  A more detailed description of these design items is given below.  


Problem Statement

A problem is defined by The American Heritage Dictionary as "1. A question 
or situation that presents uncertainty or difficulty."  In this section
you should describe in your own words the situation that presents difficulty.  
At this point we are not concerned about the solution.  Although we normally
expect that there is a solution, there may in fact be no solution.

In any case, your description here serves as a check to see if you really 
understand the problem.  If you can not describe the problem, you do not
understand it; if you do not understand the problem, you can not solve it.
Be as detailed as possible without over-explaining.  Be careful not to list
the *solution* as the problem.  


Input

List all expected input to the program.  This may be input from the keyboard
including menu choices and other types of data input.  This may be input from
a data file.  List all the ways your program will obtain input.

For each type of input, give enough examples to fully describe the range
of each input.


Output

List all expected output to the program.  This may be output to the screen
such as menus, reports and error messages.  This may be output to a data file.  
List all the ways your program can generate output

For each type of output, give enough examples to fully describe the range
of each output.


Function Call Diagram

Each programmer-defined function should be listed in a box.  It's 
relationship to the other functions is indicated by a line drawn between
the two boxes.  If FuncA() calls FuncB(), a line is drawn between the two
boxes to indicate this fact.  On the diagram, FuncA() is placed further
up than FuncB().  

		+---------+
		| FuncA() |
		+---------+
                     |
                     |
		+---------+
		| FuncB() |
		+---------+

This diagram will allow an individual to understand the structure and 
organization of the program at a glance.  No programming logic is included 
in the diagram (it is NOT a flowchart).


Pseudocode

Write a detailed description in structured english to describe the logic 
behind each function in your program.  Focus on the algorithm involved.  
How will you accomplish what needs to be done?  What steps are needed? 
in which order?  

Avoid thinking in terms of any specific programming language.  Separate the
algorithm from the *implementation* of the algorithm.   The purpose of
pseudocode is to describe your solution to the problem (your algorithm)
in some detail.

A function description should exist here for each box on the function call 
diagram. 

The structured english should use one of the following types of flow control:

	sequential statement (sum = sum + 1)
	decision statement (if x > 0 then y = 5)
	iteration (loop)
	function call (call FuncA())

Use indentation and white space to show membership.

	if x > 0 then
	    y = 5
	    increment sum by 1
	else
	    z = 10
	end if

Conclusion

These five sections can provide an initial understanding of the problem
and information for those who may have to look at your coded solution
later (including yourself).