GUIDELINES FOR WRITING DOCUMENTATION

 

• Use the Documentation Template in Microsoft Word to write all documentation. Open the template by selecting File>New and choosing CIP DOC.dot.

 

• Refer to Word Default Settings for Heading Styles to make sure that your defaults are set correctly for writing documentation.

 

• Use the Styles drop down menu to select the style, font, and font size. The styles available on our documents template are:

 

HEADING 1  (Arial 16 Bold, All Caps, Centered).

Heading 2  (Arial 14 Bold Italic) Use for the first section heading.

Heading 3 (Arial 12 Bold) Use for the second section heading.

Heading 4  (Times New Roman 12 Bold) Use for the fourth section heading.

Normal  (Times New Roman 12) Use for the body of the text.

 

Do not enter additional space before or after the heading. Spaces are automatically created as a part of the heading style.

 

• Use direct language.

 

Example:          Display the bibliographic record.

Not:                 The bibliographic record should be displayed..

Example:          Claim missing issues.

Not:                 Missing issues need to be claimed.

 

• Be consistent within a document in the use of punctuation such as periods, colons, etc.

 

• Use short paragraphs and sentences.

 

• Use concrete rather than abstract words.

 

• Use complete words rather than contractions.

 

Example:          Do not overlay the bibliographic record.

Not:                 Don't overlay the bibliographic record.

 

• If using abbreviations or acronyms, define them the first time you use the abbreviation.

 

Example:          Library of Congress (LC)

Example:          Purchase Order (PO)

 

• Skip a line between directions and example(s).

 

• Avoid fancy text boxes, borders, and non-standard bullets or spacing. If your document requires columns, use tables instead of tabs or columns. If your document requires a box around a paragraph, use a table.

 

• If your document states for example "There are four steps…" list those as four numbered sections: 1. 2. 3. 4.

 

• Do not use colored text.

 

• Do not use extensive underlining or all caps in the text.

 

• Use an underscore to represent an undefined value in a MARC tag.

 

• Use the vertical dashes (|) to represent a delimiter. (Shift \)

 

• When referring to individuals, use job titles rather than personal names if possible.

 

 

 

NCR 07/31/2002

 

This page has been visited times since 04/11/05

 

For questions about the content of this page, please contact Nancy Rubenstein nrubenst@mail.smu.edu

This page is maintained by Angela Laack and John Milazzo.

Last updated 07/31/2002