Introduction

This guide supplements work instruction PR2-W3 - Document Formatting. It gives a detailed outline of the recommended document formatting standards for reports. You should use the standard Word template, which has been configured to conform with these guidelines.

1. Document production
1.1. Document orientation
1.2. Document organization
1.3. Document format
  1.3.1. Double sided
  1.3.2. Table of contents
  1.3.3. Page size and margins
  1.3.4. Headings
  1.3.5. Body text
  1.3.6. Bullets
  1.3.7. Representing screens
  1.3.7.1. Overview
  1.3.7.2. Screen capture techniques
  1.3.7.3. Screen requirements
  1.3.8. Keyboard function keys
  1.3.9. Numbered lists
  1.3.10. Figures & numerals
  1.3.11. Justification
  1.3.12. Italics
  1.3.13. Emphasis
  1.3.14. Hyphenation
  1.3.15. Acronyms & jargon
  1.3.16. Widow/orphan protection
  1.3.17. Paragraph numbering
  1.3.18. Other considerations

All material in the user guide with the exception of appendixes should be presented in "portrait" format. Mixed orientation in the body of the document simply confuses the user, and requires constant turning of the document to read the contents.

Copies of reports output by a system should be included in appendixes and so may be produced in "landscape" format due to their width.

1.2. Document organization

The report/document should be organized according to work instruction PR2-W2.

1.3. Document format

The report/document should be formatted according to work instruction PR2-W3. The details which follow supplement the mandatory requirements of the work instruction.

This section outlines a uniform set of formatting standards which enable a reader to find the information they need with a minimum of time and effort.

1.3.1. Double sided

The report/document should be produced as double sided documents from a single sided master. This reduces the bulk of the document, and makes it easier to read as this adopts the normal "open book" format familiar to most readers.

1.3.2. Table of contents

The document contents list is located after the preface page and should comply with the following:

• Be titled "Contents" not "Table of contents".
• Contain the headings from the document broken down and arranged into a logical groupings.
• Contain all headings up to but not exceeding level four headings. The document itself should have no more than four levels of headings.
• Illustrations lists should be shown.
• Appendix(es) should be shown.
• Page numbers are given for each entry and are joined to the entry by a leader string (row of dots).
• TOC text should use the following font attributes:

• Level one TOC entry should have a narrow ruling line beneath.
• Header/footer.

If the document being produced does not have a table of contents, it is good practice to design the document before beginning work by making a list of the headings which will form the contents list.

As a general guide, the organization of a document should reflect a logical sequence, whether a chronological sequence, a progression from the general to the specific, or other meaningful sequence.

1.3.3. Page size and margins

Page setup should have the following attributes:

• Page size - A4.
• Margins (left & right) - 2.54 cm.
• Margins (top & bottom) - 3.17 cm.
• Header & footer - 1.25 cm in from edge.
• Gutter - zero cm.

Document headings should have the following attributes:

• No more than four levels of heading should be used.
• Headings should be indented according to their level of significance in accordance with the following table.

Level one and two headings should have a ruling line beneath, as shown in the above table. The ruling lines should be 4 pts. beneath the text and extend from the beginning of the heading across to the right margin.

All headings should have the first word capitalized and subsequent words in lower case. Proper nouns (i.e. Queens land Rail) have the first letter capitalized wherever they appear in a heading.

Note: This guide species the use of Arial and Times Roman fonts since these are excellent general purpose fonts available on most computers. As a general rule, stick to these two fonts where possible. If unavailable use another similar font. Avoid the use of unusual or fancy fonts unless you have a specific need.

1.3.5. Body text

The body text should have the following attributes:

• Be left justified (i.e. aligned to the left, leaving a ragged right edge).
• Times Roman (TT) 12 points.
• Indented 3.75 cm from the left margin.
• Space - zero points above and six points below.

Bullets are used for lists where the order is not important. Bullet points should have the following attributes:

• Times Roman (TT) 11 points.
• Indented 3.75 cm from the left margin so that bullet character is in line with body text.
• Bullet character a 10 pt. filled dot.
• Hanging indent of 0.5 cm from bullet character to start of text.
• Space - zero points above and three points below.
• Bullet points should only be used for lists of two or more points (i.e. no single bullet point).

Generally, putting screens into your manual is to be encouraged, but the decision to include them will be influenced by several factors:

• Expertise with computers - the reader's expertise with computers and software. Screen images are good where the reader is not comfortable or familiar with computers. Screens are helpful in showing the reader what they should be seeing. Where the reader is highly experienced, screens are less important unless;
• Specific Information - there is specific information on the screen about which the reader should be aware. In this case the same information needs to be highlighted in the main text as well as the screen.
• Maintainability - manuals with screens usually need more maintenance than those without. That's because those without are less likely to be affected when changes are made to the software. Think about how much time and effort is likely to be available for maintenance. Since inaccuracies like incorrect screens are a quick way for people to lose confidence in a manual, it's better to leave screens out if there's not enough time to maintain them properly.

If you do decide to include screens, you need either:

• Screen capture - a screen capture program which takes a snapshot of whatever is on the screen at a given time and saves it as a file which can then be imported into your document. There are several different products on the market which do this, ranging from inexpensive share ware up to sophisticated products that allow the file to be saved in a wide variety of formats.
• Windows - if you're familiar with Windows and the software to be documented is capable of running in a window, a utility is available on the menu that appears when the button at the extreme top left corner of the window in which the application is running is pressed. Select the option to "Edit" from this menu, then "Mark Area" to mark out with the mouse cursor the area to copy. The marked area is now in the clipboard and can be pasted into Notepad where it can be saved as an ASCII file.
• Screens that are saved as images are usually much larger than those saved in ASCII format. The document quickly becomes very large (i.e.. over 100Kb) when more than a few images are included in it. So saving the file in ASCII format is recommended since it takes up less space.

Screens include data input screens, enquiry screens, and job submission screens.

The information displayed in screens should be meaningful but not refer to actual people or situations. Likewise, no sensitive information should be displayed. Screens should have the following features:

• Be indented so that the left edge lines up with the body text, and it should have ruling line around.
• No shading - it is not necessary to shade the screen to give it more of a "screen-like" appearance.
• A non-proportional font like courier should be used to represent screen text where possible.
• The screen should be labelled at the bottom left corner of the box. This label should be highlighted in bold, and show the business function name followed by the screen name. For example: Transfer Menu: Set up a Transfer - Transfer Details
• Screens should not carry over onto the next page.

Keyboard function keys (including program function keys and keyboard control keys) should be represented in upper case bold enclosed within angle brackets. For example:

Numbered lists are used where the order is significant, such as in procedural steps.

The attributes for a numbered list are the same as for bullet lists, with the substitution of Arabic numbers (i.e. 1, 2, 3) for bullet dots and a hanging indent of 0.75 cm after the number to accommodate double digits.

1.3.10. Figures & numerals

Decimal numbers less than 10 shown as numbers (i.e. 6.5). Whole numbers less than 10 are spelt in full. Spaces are used for numbers with four or more figures (i.e. 10 000).

1.3.11. Justification

Justification styles should be as follows:

• All heading, body text and bulleted/numbered lists and captions left justified.
• Table headings and table contents may be left, right or centered.

Italics should be used for the following:

• To add emphasis to words, phrases or sentences.
• Foreign words (i.e. ad hoc).
• Titles of publications (i.e. Concise Oxford Dictionary)

Emphasis can be achieved in the following ways (in ascending order of emphasis):

• Italics.
• Bold Italics.
• Callout character - as follows:
• Add emphasis to a paragraph with a callout character. Words within such a paragraph may be further emphasized with italics or bold italics.

Hyphenation is not obligatory. Many people prefer not to have body text hyphenated since it slightly increases the difficulty with which a reader scans a line, although the difficulty in many cases is negligible.

Where done, hyphenation should be made as follows:

• The break is made after a vowel with the second part beginning with a consonant (i.e. people).
• For multiple part words the practice of hyphenating words is decreasing, so as a general rule don't hyphenate if in doubt. For example, cooperate multi tasking.
• Fractions are hyphenated (i.e. two-thirds, five-eighths). Compound words like day-to-day task-sharing are hyphenated.
• Enable automatic hyphenation where this is available in your word processor.

While the use of acronyms and jargon can be justified in some cases, they should be avoided where possible. Where acronyms are used they should be defined in the definitions and acronyms section and also defined the first time they are used in each chapter.

Only acronyms used in the current document are to appear in the definitions & acronyms section.

1.3.16. Widow/orphan protection

A "widow" is the last line of a paragraph that appears alone at the top of a page. An "orphan" is the first line of a paragraph that appears alone at the bottom of a page.

Use the widow/orphan protection option in your word processor to prevent this occurring in the document.

1.3.17. Paragraph numbering

While headings can be numbered, avoid paragraph numbering the body text unless there is a specific need to use it.

1.3.18. Other considerations

Abbreviations - use fulls tops with abbreviations and contractions. For example Fri. for Friday.

Punctuation Spacing - one space only after any punctuation mark.