Documentation Requirements:

Written documentation must be prepared as a single Word file named in accord with the convention:

<assignment-designator>.doc

where <assignment-designator> is given by <account-id>-<assignment-nmbr>.

For example, for a student with account-id "n12345678", the <assignment-designator> for assignment 1 is "n12345678-1", so the documentation is to be submitted as a file named

"n12345678-1.doc".

Each section of the documentation must be clearly identified in a manner that facilitates locating it. The only allowed fonts are Times New Roman and Courier. Point sizes should not exceed 12 and should not be less than 10. The basic text color should be black, with colors, bold face, underline, and italics used sparingly and only for special emphasis. The Courier font should always be used for text derived via Osprey (especially important for log files).

Documentation is expected to be of professional calibre. Your work will be graded for

• technical content
• overall organization
• general quality and clarity of writing
• sufficiency and brevity of content
• discriminating choice of included material
• adequacy and purposefulness of testing
• overall appearance.

Your documentation file is to be derived from the template file Template.doc available via the web or for ftp download from the /usr/public/cop3601/cwinton directory. The template provides a uniform (and hence predictable) cover page for Word submissions. Its appearance is as follows:

The documentation report for a programming exercise is to be organized as follows:

1. Executive summary (1 or 2 pages)
   1. Purpose (comprehensive statement describing the problem and its elements)
   2. Approach (how the the elements of the problem are addressed)
   3. Constructions employed (overview of what is built to address each element of the problem and why)
   4. Testing plan, summary and discussion (a list giving each test case documented in the appendices, why it is used, and what it shows)
   5. Wrapup assessment (statements explaining results, features not tested and why, and specifications not met and why)

2. Appendices (source code, input/output files, and log files))
   • Table of Contents (one entry for each identified appendix)
   • one or more appendices, with comments and explanatory annotations, for each of the following categories:
     1. Program source code

     For SIC or SIC/XE programs both source and object code should be given, using the style of the ".lst" files produced by the sicasm assembler. For C programs variables should be given names with self-evident meaning; a lead comment block should be incorporated into each program that identifies major data objects and their structure; the code should have a consistent style such as that discussed in the Course Supplement ; code should be indented in a manner analogous to that produced by the Unix command indent.

     2. Test file listings and results
     3. SICSIM or other log files

Note that for each programming exercise, an annotated version of your program code is to appear as an appendix. In general, any included program code must be commented by some combination of italicized annotations, appropriate high-lighting, meaningful variable or other identifier names, and imbedded comment lines. It must be possible to follow the program logic. If it is difficult to follow the flow of program code, penalty points will be assessed.

Also note that test data and resulting output (where applicable) are to be included as appendices. If multiple test cases are needed, you need to include the test data listing and the corresponding output results for each case (appropriately annotated). For SIC or SIC/XE programs you must include a commented, (lightly) high-lighted printout of the log file ("sic.log") of a comprehensive simulator session. Drivers for testing C program modules will generally produce a similar log file ("hlib.log").

As a rule, documentation is judged by its usefulness to someone tasked with maintaining or utilizing your work (think in terms of what would you need 6 months down the road). To reiterate: be sparing in your use of high-lighting; too much is distracting.

Click here for an illustration of the documentation file.

Important: If an assignment is identified as having Part A and Part B, there is still to be only one documentation file. In this case the documentation file is to be organized into 2 sections, one labeled Part A and the other Part B. Each section is to have an executive summary followed by appendices. In no case should the appendices for one part be included with appendices for another part. In no case should the write-up for one part be copied to be the write-up for another part (this is a temptation to be avoided in preparing summaries).

Submission Procedure:

Your submission is to include

• the documentation (.doc) file

and raw copies (as opposed to annotated versions imbedded in your documentation) of

• source files
• make files (for C programs)
• test files (input and output)
• log files

all of which have been named as specified in the assignment description.

With the exception of C source files for assembler components used in multiple assignments, files generally are to be named according to the file naming convention:
      <assignment-designator>.<file-name>
where the assignment designator is as described above. Log files, such as the "sic.log" file generated by the SIC simulator need to be renamed before you submit them. You should recall that on a Unix system, renaming a file is handled by the mv ("move") utility, in this case:
     mv sic.log <assignment-designator>.sic.log

The class directory /usr/public/cop3601/cwinton contains a shell script named submit which you should copy to your own file space. The submit script combines your submission (documentation and attendant files) as a "shar" file and submits it using the "turnin" utility on Osprey. More importantly, it enforces the naming conventions of the assignment spec; any missing or incorrectly named files in a submission will likely cost you points. Usage is simple; e.g., for assingment 1
     submit 1

To transfer files to and from Osprey it is suggested that you use the (non-commercial) SSH Secure File Transfer (freeware for educational use). If you use any other product supported by the UNF system (ftp is NOT supported), be sure that your documentation (.doc file) gets transferred as a binary; this is automatic when using SSH.

DO NOT SUBMIT ANY EXTRANEOUS CLUTTER OR EXECUTABLES.