Software Engineering Project Documentation Guidelines

CS 410/560 - Winter 2017

The documentation you produce will be the key to the continued usefulness of your project. It should be well organized, as precise as possible, and describe your actual product. For a future maintenance programmer, it should be a useful key to understanding how the project works, and correspond to the code that will need to be maintained.

This outline is simply a suggestion for organizing the document, and what should go in it. (ordering is optional)

  1. Table of contents
  2. Introduction. Who did it, what is it for.
  3. Requirements specification. This tells What the software does (is required to do.) Be as precise as possible.
  4. Design: How you implement the requirements
    1. Overall design (architecture). How the project is broken into modules (classes), what  the responsibilities of each module are, and how they communicate. High cohesion within modules, and low coupling between, are desirable. One or more diagrams would be helpful.
    2. User interface: What the user needs to know about how to interact with the software.
    3. Likely changes: Define areas that are considered likely to change
    4. Detailed design of each module. Its interface, what each function (method) does, algorithms used, how exceptions are handled. Useful to both implementer and maintainer.
  5. Blind alleys -- what doesn't work. Save the maintainers. As Parnas puts it, "..Record all the design alternatives that we considered and rejected. For each, explain why..."
  6. Test plan. Test cases that try to cover the requirements, criteria for acceptance. Tests for each module, if possible.
  7. Implementation: The source code. One or many files. We hope it is well structured and commented enough that a maintainer can find the functions described in the design.
  8. User Manual
  9. Disposition: Do you copyright your project? What should I do once I have graded it? This could range all the way from, "Give it all back and destroy the evidence," to "Keep it and give it away to anyone interested." You might consider attaching a copyright notice to your code, such as the Gnu Public License (GPL).

Requirements Document Organization

Parnas gives this outline of a document for a real-time system: (some of which got into the above)
  1. Computer Specification: Machine or software required.
  2. I/O Interfaces
  3. Specification of Output Values 
  4. Timing constraints
  5. Accuracy Constraints
  6. Likely changes
  7. Undesired event handling

What to submit to me

I don't need any "hard copy". 

Documentation can be emailed or otherwise given to me in some form that I could reasonably be able to print or view on a screen.
Code, I would appreciate in a form that I would be able to compile, as well as read.
An executable, such as a compiled C program or a jar file. If it can't be run in J-118, allow me access to a system that it will run on.
I will be willing to return amy physical objects that you give me. I doubt that I will ever use the floppy disks I have from previous years. (see "Disposition" above)