Java: Details of Program Documentation

Details of Program Documentation

General Comments

This page is meant to give you ideas about documentation format and content, but do not be too constrained by these ideas.
For the first project I am not expecting much detail, but the second project should be more thorough.
Do not write information just to have a lot of documentation or try to sound impressive. Keep it short, clear, relevant and useful.
Focus on issues specific and unique to your topic, not on things that are the same for all students doing their projects.
Focus on programming issues, not on social impacts, management issues, etc.
For a detailed example of user and technical documentation, see my English/Swahili quiz program at ../swahili/index.htm.

Project Proposal

Goals: What will the program accomplish? How will the target users benefit?; Is there a significant improvement over other methods such as paper files, a calculator, another software package?
Basic functional specifications: This is the most important part of the proposal.; What will the program do? What are the main inputs, calculations and outputs? Be specific.
Target users: Who will use the program? What are their characteristics?; You might not need to go into much detail for these projects, especially if your program is for a general audience.
Content sources: What books and electronic sources did you consult?; Be specific enough that someone else would be able to find it. Include page numbers and URLs.; If you searched google.com and yahoo.com, don't just mention those sites; mention specific sites where you found useful information about your topic.; What existing software is available to perform similar functions?; Find out if spreadsheet or database programs offer similar functions and features, and their strengths and limitations.; List advantages and disadvantages of writing a custom program instead of an office application.; If you will be sharing ideas with others, mention their name(s), but remember that you must do your own work to receive marks.
Method to choose topic: Mention your interests and motivations.; Mention sources of topics you consulted including the course web site and instructor but also books and web sites that have programming topics.
Scope: What features will the program not try to implement?; Important: You must submit a program that compiles without any errors.; It is far better to produce a simple program that works than a complicated one that doesn't.; Start simple and get it working. Add on more if time permits.

Design Specification

Schedule: List the tasks you will perform and the dates during which you will perform them.; For a small project like this you do not need too much detail.
Tools: List the software tools you will use for application development, debugging, word processing, image editing, etc.
Functional specifications: What will the program do?; How will the user interface look? Graphics-based or text-based? Interactive, batch or both?; Will the user be presented with a menu of choices or a series of questions?; Will the user type input or send input from a text file? Will the output be sent to the screen or a text file?; What are the range and types of inputs? What will the user see for unacceptable inputs?
Technical specifications: How will the program be designed internally?; What classes of objects will be used? For each object, list and briefly explain its attributes and methods.; It may be useful to start by creating the skeleton of code with class and method declarations and comments but without any method implementation.; What algorithms will the key methods use? Explain algorithms using English or pseudocode.; What mathematical formulas are used in calculations? Explain each variable.
Diagrams: For these projects you can submit hand-drawn diagrams on paper since diagramming using a computer can be difficult and time-consuming.; Show the relationship between your objects (e.g. is-a, has-a) and the flow of messages and data between the objects.

Technical Documentation

Code documentation and format: Every class and every method in your code should have a Javadoc comment of at least one line.; Important sections within methods (e.g. complex algorithms and calculations) should have additional comments.; Code should follow the recommendations for naming and coding style and class structure.
System Requirements: What special system requirements does the program have? (e.g. memory, disk space, etc.); For small programs, the main requirement is a system that supports Java applications and applets, e.g. has the Java SDK installed.
Installation: Pretend you put a .zip file on your web site containing the program. How does the user unzip, install and compile the program?
Running: How does the user run the program?; Is the program graphical or text-based? Is it interactive or batch? Are there any command-line options?
Bugs: What doesn't work as it should? Are there any bugs that you have not corrected? Describe the problems briefly.
Limitations: Is the program limited to a certain number of objects or data inputs?; Are there constants with fixed sizes that limit the user's amount of data?
Future Features: What changes could be made and features added to a future version relatively easily?

User Documentation

Overview: What is the purpose of the program? Why would someone want to use it?; What can the program do? What are its main features?
User Interface: What choices will the user see? Explain each choice or menu item, perhaps in the form of an outline.; What should the user do or not do? What inputs are valid and invalid?; Answer the user's common questions, e.g. "how can I ...?"
Examples: Give examples of input and output, e.g. a test run.