|
|
Version: 1.0
August 15th, 2002
Contents of Formatting Guidelines:
Production Tools
All project documents should be created directly
in html form.
Figures, graphs, and other images are normally displayed from
a JPG or GIF file.
If specialized tools or procedures are used to create documents
or images, these should be documented in the home/ directory as
part of the team's notes documenting their work. Such notes should
describe which tool(s) was used to create the document(s)/image(s),
the name(s) of the source file(s), where the image(s) was used,
and any special instructions for using or modifying the image(s).
Formatting of documents
- Strive for consistency of style across the documents produced
by your team.
- Use exactly the section numbering given in the document
outlines.
- Font choice and size should allow for easy readability of
the final document. The normal font size is generally the best
choice for the body of text in a document. Do not try to be
too fancy, since this can reduce readability and usability!!
- Tables can be very helpful in organizing information. As
a general rule, ensure that tables are set to have percent
widths rather than pixel widths; this allows the table
to automatically resize to fit within a browser's window.
- Utilize the "real estate" of each document as effectively
as possible. Be judicious in the use of mechanisms such as border
frames (which can be used, for example, to add color).
- In general, each document should be self-contained, i.e.,
not split across several html pages. On the other hand, making
a document easy to navigate is important.
- Some teams may choose to use style sheets; this is allowed
as long as the style sheets work well on platforms used
at KReSIT. (discuss this with your coordinators at KReSIT).
Use of HTML tags
- The <TITLE> field should contain the Topic name,
student group coordinator name, and document name and version, for example:
SNMP-amit, SRS version 1.0
- Section and subsection headers should use heading styles
to help them stand out. In html documents we recommend
- For section headings: <h3> ("large heading")
- For subsection headings, use the next smaller heading: <h4>
("small heading")
- For sub-subsection headings, use the next smaller heading:
<h5> ("smaller heading")
- 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 visual organization
of your document.
Opening banner
- Appears in every project document. (The opening banner is
analogous to a cover page.)
- 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 for this document
- Date of the document
- Project title
- Team title
- Guide, Co-Guide, KReSIT group coordinator name
- A list of the authors (i.e. the group members)
- As the document is in html:
- The opening banner will be the first half-screen or so of
your document
Table of Contents
- Include a Table of Contents (ToC) in every project document.
- The ToC follows immediately after the opening banner.
- The ToC should include all section and sub-section titles
(including the numbering).
- Use indentation within the ToC to show the structure of the
(sub-)section levels.
- Precede and follow the ToC with a horizontal rule <hr>.
- Include anchor links to each entry in the ToC to allow a
reader to jump directly to each section.
If document is in HTML
- The running header is set when you print the document. (In
other words, the running header is not defined as part of an
HTML document itself.)
- The print header should contain the following information,
preferably with the information located in the recommended position
|
Required contents |
Recommended Position |
| Title (from title field) |
Top left field |
| Location (i.e. the URL) |
Bottom left field |
| Page number |
Top right field |
| Date of document |
Bottom right field |
- Browsers on some systems (primarily Unix) do not have the
capability of printing a running header. If all else fails, fill
in minimal information by hand;
Change Log
As a document evolves, its 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 group'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 change log should be located at the end of the entire document.
You can see one example of a change log below.
Note that for these documentation
standards, the version number is the same as the date of issuance.
Change Log for the General Guidelines:
- January 16, 2002: Minor clarifications in wording
- February 2, 2001: Modified wording in several sections to
clarify intentions.
- October 5, 2000: Added the section describing Change Logs
- August 26, 2000: Baseline version for documentation standards.
|
|
