TCSS 360
Project Document Layout Requirements

Version: 16 November 2001

Document Type

All text documents handed in should be HTML (Hypertext Markup Language) documents. Figures and graphics should only be in jpeg or gif format. Any documents handed in using other formats (e.g., ".doc", ".rtf", or ".txt" documents) will be returned ungraded.

Your documents should be handed in on a single diskette, zip disk, or CD, labeled with the date, the groupname, and the milestone. Please place this diskette into a 9"x12" manila envelope or in a diskholder so that the disk is protected from the elements. No hardcopy should be handed in, as this will only waste a considerable amount of paper. Make sure to view your document on the disk to ensure that all hyperlinks are working (see comments below on case sensitivity of filenames).

What to include

For each handin, you should have a top-level file that is called index.html. This file should have any accompanying or supplemental documents hyperlinked at the appropriate place, so that a reader can easily navigate through your entire milestone starting from this file. In addition, this file should have a brief narrative that describes each document in the handin and guides the reader as they navigate the project milestone.

For the second and subsequent milestones, each of the documents produced during previous milestones, but updated to reflect changes to the project as it evolves should be hyperlinked from the index.html document. That is, all of your documents should be synchronized, and each handin should reflect the current state of each document produced to date. Your change log for each document should briefly document each change, as described below. In addition, you should make sure to include links to each of your meeting minutes.

Naming

You are free to use any naming or directory structure convention that is convenient for your files (other than the "index.html" file). Note, however, that your file and directory names as well as your hyperlinks should be case-sensitive. This is because, although Windows is not case-sensitive, linux is case-sensitive, and hence, many of your hyperlinks that would work in Windows will not work on linux, which is the system that I may use to view your projects. Handins with broken hyperlinks and case-insensitivity problems may be returned ungraded for rehandin after fixing. In addition, you should make sure to reference your hyperlinked files using forward slashes for directories ("/"), since this will be recognizable from both Linux and Windows, while the backslash is recognizable only from Windows. Your filenames should not contain any spaces -- use underscores or dashes as separators if needed. Finally, make sure that hyperlinks to other project documents are all "relative references", so that your project hypertext document is fully portable and does not require Internet access. It is fine to include hyperlinks to external websites for non-project website references, i.e. for documents that your group did not create but which your group has used as a reference source (e.g. Java API's, Java coding standards, SRS template, etc.).

Formatting of documents

You are to hand in a hypertext document, not a website. Simplicity and clarity should be the predominating characteristics, not flashy graphics or interactivity.

Students have experienced many problems in the past using word processors for creating their documents (e.g. MS Word) and then having these applications generate "html" format. As a result, create your documents directly in "html". Please use the style defaults, and do not include any frames, forms, javascript or other dynamic features (unless you first clear this with me). You should only need to use a few basic tags; the following set should suffice:

title, html, body, head, ol, ul, li, p, br, hr, table, tr, td, a 
(anchor), h1-5 (section level), em, strong, samp, var, dl, dt, dd

Overall guidelines

• Strive for consistency of style across the documents produced by your team.
• Use the section numbering given in the document outlines that you are utilizing when possible.
• Font choice and size should allow for easy readability of the final document. The default font size is generally the best choice for the body of text in a document.
• Tables can be very helpful in organizing information.
• Utilize the "real estate" of your document as effectively as possible. Be judicious in the use of mechanisms such as border frames (whose primary purpose is to add color).
• In general, each document should be self-contained, i.e., not split across several html pages. Images should generally be inline rather than hyperlinked.
• Use only black text against a white background.

Use of HTML tags

• Section and subsection headers should use heading styles to help them stand out.
• Each section, subsection, and sub-subsection heading should have an appropriately named anchor, which will be linked to from the Table of Contents for the document. You can also use these anchors from other documents that refer to these sections.
• Use horizontal rules <hr> to aid the usability of your document.

Opening banner

• Appears in every project document.
• Introduces the document with all identifying information.
• For all documents:
  • The opening banner is the first information to appear
  • The fonts should be of an appropriate size. Use a pleasant mix of the largest headings (<h1>, <h2>, <h3>).
  • It is good to vary font size for the various parts of the opening banner.
  • The following information must appear in the opening banner:
    • Document title
    • Version number/name for this document (date should be used as the default)
    • Date of the document (if not used as version number)
    • Product name
    • Team title
    • A list of the authors (i.e. the team members)

Table of Contents

• Included in every project document.
• Provides an overview of the document.
• Follows immediately after the opening banner.
• For all documents:
  • Include all section and sub-section titles (including the numbering)
  • Use indentation to show the structure of the levels
  • Include anchor links to allow a reader to jump directly to each section

Example Layout

Here is an example index.html from a student project group, modified (by me) to meet updates to my formatting requirements.

Change Log

As documents evolve, the version number changes to reflect these differences. A change log informs the reader of the differences between versions. Documents receive new version numbers each time a different version is turned in or added to the team's web site.

There should be an entry in the change log for every version of the document. This should include:

• the version number
• the date it was issued
• a sentence or two describing the reason for the new version
• the person who made the change

The change log should be located at the end of the entire document. Note that for these documentation standards, the version number is the same as the date of issuance.

Change Log

• November 16, 2001. Changed to create "html" file directly w/list of tags. Also, provided a sample index.html file.
• November 1, 2001. Added sample index.html file.
• October 30, 2001. Added add'l constraint for single name file names and also black text against white background.
• August 29, 2001. Added comments on forward vs. back slash for directory names in hyperlink references.
• April 9, 2001. Added comments on case-sensitivity and handin via softcopy.
• March 1, 2001. Edited version of original.
• Original version by Vicki Almstrum, University of Texas