ADMIN 3.

4 Document Style Guide for Standards Version 3 August 2012

ABN 5810 5001 465

ADMIN 3.4
Document Style Guide for
Standards
Version 3


















K .B. Taylor
CEO RISSB
27 August 2012

Document Style Guide for Standards




ADMIN 3.4 Document Style Guide for Standards Version 3 August 2012


DOCUMENT CONTROL
Identification

Document Title Number Version Date
Document Style Guide for Standards ADMIN 3.3 1 23/11/2007
Document Style Guide for Standards ADMIN 3.3 2 04/02/2010
Document Style Guide for Standards ADMIN 3.3 3 27/08/2012


Document History

Publication Version Effective Date Page(s) Affected Reason
1 23/11/2007 All Document Creation
2 04/02/2010 All Review and update
3 27/08/2012 All Review and update


Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 3 of 15

Table of Contents
Identification .......................................................................................... 2
Document History .................................................................................... 2
Document Style Guide for Standards ............................................................... 5
1 Purpose .............................................................................................. 5
2 References .......................................................................................... 5
3 Process .............................................................................................. 5
3.1 Scope............................................................................................ 6
4 Using this Style Guide ............................................................................ 6
4.1 Writing Expression ............................................................................ 6
4.2 Paragraph and Sentence Length ............................................................ 7
4.3 Less is More .................................................................................... 7
4.4 Page Size ....................................................................................... 7
4.5 Embedding an Image ......................................................................... 7
5 Document Style and Structure .................................................................. 7
5.1 Headers and Footers .......................................................................... 7
5.2 Appendices ..................................................................................... 8
5.3 Element Structure ............................................................................ 8
5.4 Identification .................................................................................. 8
5.4.1 5.4.1 Standards .......................................................................... 8
5.4.2 Section and Clause Numbering ........................................................ 8
5.4.3 Tables, Figures and Equations ......................................................... 9
6 CONTENT ............................................................................................ 9
6.1 Language and Units ........................................................................... 9
6.2 Introductory Section .......................................................................... 9
6.2.1 Disclaimer Section ....................................................................... 9
6.2.2 Document Control Section ............................................................. 9
6.2.3 Content Section .......................................................................... 9
6.2.4 Purpose Section .......................................................................... 9
6.2.5 Scope Section ............................................................................ 9
6.2.6 Compliance Section ..................................................................... 9
6.2.7 Referenced Documents Section ....................................................... 9
6.2.8 Definitions Section ...................................................................... 9
6.3 6.3 Requirements ............................................................................ 10
6.3.1 Terminology ............................................................................. 10
6.3.2 Uncertainties ............................................................................ 10

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 4 of 15

6.3.3 Ambiguous requirements .............................................................. 10
6.3.4 Realistic requirements ................................................................. 10
6.3.5 Verifiable requirements ............................................................... 10
6.3.6 Repetition ............................................................................... 11
6.3.7 Performance and prescriptive requirements ....................................... 11
6.3.8 Source quality ........................................................................... 11
7 Document Factors ................................................................................ 11
7.1 Document Control ........................................................................... 11
7.1.1 Identification ............................................................................ 11
7.1.2 Preparation & Approval ............................................................... 12
7.1.3 Distribution and Change ............................................................... 12
7.1.4 Document History ...................................................................... 12
8 MS Excel Document Format .................................................................... 12
8.1 Section and Clause Numbering............................................................. 12
8.2 Location and Alignment ..................................................................... 12
8.3 Font ............................................................................................ 13
8.4 Colour .......................................................................................... 13
8.5 Requirements Classification ................................................................ 14
8.5.1 Use of Type Column .................................................................... 14
8.6 Interface Coordination ...................................................................... 14
8.7 Background Information .................................................................... 14
8.8 Single, simple requirements ............................................................... 15
9 Record Requirements ............................................................................ 15


Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 5 of 15

Document Style Guide for Standards
1 Purpose
The purpose of this document is to provide RISSB users with a style guide
that regulates the creation and development of RISSB Standards documents.
2 References
All Terms, abbreviations and acronyms used in this document are defined in
the RISSB Quality Management Glossary
3 Process
This guide should be used in conjunction with the Master Template from
which all future standards document development is based.
This procedure is based on MS Excel style documents. MS Excel is
predominantly used for technical standards that are used to document
requirements, whereas MS Word is used for non-technical standards e.g.
Rules, Codes of Practice and Guidelines. The Project Manager will direct the
style of document to be developed, as per Figure 1.


MS Excel Template MS Word Template
Rules, Codes of Practice
or Guidelines
Requirements based
What type of document
is to be produced?
PM receives
Request for Development

Figure 1: Project Decision
Document templates are available from the Project Manager. The template
provided is designed to comply with this procedure and therefore, in most
cases, this is all that the author requires.
Documentation read as if produced by a single writer. While the style and look
of the document have some bearing on this, it is most important that the
writing itself be consistent.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 6 of 15

3.1 Scope
This style guide has been produced as a RISSB procedure, to be used in
conjunction with the authorised templates, for all personnel who, from time to
time, are involved in document production.
These documents include the following:
Standards
All documentation created and produced under this style guide, will be
required to conform to the RISSB Documentation Standard.
The RISSB Documentation Style Manual contains a comprehensive body of
material to assist in the preparation of standards. It sets out the guidelines
and specifications to be applied to the following areas of document
preparation:
Planning
Templates and Styles
Design and Layout
Writing Style
Miscellaneous
Each of these general categories is further divided into associated topics.
4 Using this Style Guide
The purpose of this style guide is to show you how to present your material in
a manner that is informative, well laid out and highly professional, while
conforming to RISSB guidelines.
This guide should be used in conjunction with the Master Template, which
contains the basic set of styles and features that you are likely to need for the
creation and production of most documents within RISSB. Templates contain
sub-sets of the master templates styles and features.
4.1 Writing Expression
Writing style varies from writer to writer.
However, there are certain guidelines that should be observed to ensure that
all writers are consistent in their approach to producing technical
documentation.
Requirements in Standards are typically written in a repetitive structured
manner e.g. lists of the thing shall do/equal/be etc something, where
thing and something are clearly identified and the something is verifiable.
They are not written to be an exciting read.
Avoid using following:
Sexist language. Use second person.
Technical jargon or terminology that is not explained in the Definitions.
Non-English words and phrases, such as laissez-faire or ad hoc.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 7 of 15


4.2 Paragraph and Sentence Length
For standards, there is to be one uniquely identified requirement per sentence
(row).
4.3 Less is More
Less is more is often when writing about technical subject matter.
Your primary goal, as a writer, is to convey meaning in the simplest possible
terms in plain English.
Keep any requirements and supporting explanations simple and as short as
you can. Users are relying on your writing and language skills to gain their
understanding from what they are reading.
Ambiguity should be scrupulously avoided. Using a dictionary and a
thesaurus to assist in this aspect of your writing.
It takes just as much effort to write a concise document as it does to write a
rambling treatise.
4.4 Page Size
The standard page size for RISSB standards documentation is A4 in
landscape mode.
4.5 Embedding an Image
Embedding images into a document saves the images as part of the
document. This can result in extremely large file sizes if the original graphics
files are too large and/or numerous.
Depending upon the resolution, dimensions and colour depth of each image
1 bit (2 colours preferably) the document can become very large, very
quickly.
However, if you feel that the images will not have a major or detrimental effect
on the documents file size, you can proceed on the basis that the resolution,
dimension and colour depth of the images are within tolerable limits.
5 Document Style and Structure
5.1 Headers and Footers
Headers and footers are supplemental elements in a document that routinely
appear at the top and bottom of the page to provide information about the
documents properties. These properties shall include a minimum of the
following elements:
Corporate Logo
Document Name
Copyright Details
Page Numbering
The header and footer can also feature the following optional items:

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 8 of 15

Document Version
Document Registration Number
Version Control
5.2 Appendices
Appendices are parts of a document that include additional information,
pertinent to the main body of material.
The following should be used as guidelines for the inclusion of material as an
appendix to a document.
Is the material to be appended, relevant or related to the main documents
material?
Does it complement the main document?
Can it be used to gain a better understanding of the main document?
Is it compatible with the published format of the main document?
5.3 Element Structure
The standards will be based on a consistent structure comprised of elements.
The top level elements, entitled Major Elements, will form the basis of each
stand-alone standard document.
Each Major Element will cover a specific high-level subject area and will be
broken down into relevant lower-level parts called Minor Elements.
There will also be an introductory Minor Element at the start of each Major
Element refer to 4.2 for further details.
5.4 Identification
5.4.1 5.4.1 Standards
The Project Manager lists the standards to be developed and their
identification number.
Standard document names shall be preceded by their identifier and ended
with a revision date DD MMM YY.
5.4.2 Section and Clause Numbering
Identification of each Section of text within each standard shall be by
numbering in the form of 1, 1.1, 1.1.1 and 1.1.1.1.
The sectional numbering scheme should not exceed four levels, i.e. there
should be no numbering of the form 1.1.1.1.1 for example.
Clauses shall be identified by numbering in the form of 1, 2, 3, 4.
Clauses that are part of a list should be identified by a suffix to the list heading
text clause number in the form of (a), (b), (c) etc. Example: 5 The something
shall 5(a)Option 1, 5(b) Option 2, 5(c) Option 3. Each list item is to be
on a separate spreadsheet row.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 9 of 15

5.4.3 Tables, Figures and Equations
Tables, Figures and Equations within each standard shall be identified
numerically at the bottom of their cell, starting from TABLE 1 and FIGURE 1
and EQUATION 1, and include a text description, e.g. TABLE 5 - RIDE
INDEX LIMITS.
Large Figures and Tables may need to be placed in a separate Appendix
worksheet, as they do not fit legibly into the standard width
REQUIREMENTS column.
Image properties shall be set within the spreadsheet to be Move but dont
size with cells right click, select Format Picture then Properties.
6 CONTENT
6.1 Language and Units
The standards shall be written in English.
The standards shall use the metric system for units of measurement.
6.2 Introductory Section
6.2.1 Disclaimer Section
Section 1.1 of each draft standard shall contain the disclaimer, as given in the
template.
6.2.2 Document Control Section
Section 1.2 of each standard shall contain the content described in section 5.1
of this procedure.
6.2.3 Content Section
Section 1.3 of each standard shall contain a table of contents and a generic
description of the details of the spreadsheet layout (as given in the template).
6.2.4 Purpose Section
Section 1.4 of each standard shall succinctly state what the standard is trying
to do and what high level risk(s) the standard is trying to control.
6.2.5 Scope Section
Section 1.5 of each standard shall succinctly state what the standard applies
to, any conditions of applicability, and any exclusions.
6.2.6 Compliance Section
Section 1.6 of each standard shall contain a statement on compliance, as
given in the template.
6.2.7 Referenced Documents Section
Section 1.7 of each standard shall contain a list of the documents referred to
in the standard.
6.2.8 Definitions Section
Section 1.8 of each standard shall describe the meaning of any terms that:

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 10 of 15

have a specific meaning or application in the standard
are unusual
are abbreviations or acronyms
describe items that may have different descriptions in the industry
Where terms have already been defined by previous standards then the same
definition should be used. The Project Manager will supply the Authors with a
glossary of previously used definitions.
6.3 6.3 Requirements
6.3.1 Terminology
Use a consistent description for an item. Use the same term as given in the
Definitions section.
Avoid the term it as in it shall use the consistent description e.g. the
item shall
Use simple language avoid jargon, unfamiliar terms and abbreviations.
Check definitions against any supplied glossary.
Use shall for mandatory requirements.
Use should for recommended requirements.
Avoid proprietary products or names where possible. Acknowledge any
proprietorship (trademarks etc).
Use spell check when finishing a draft.
6.3.2 Uncertainties
Avoid requirements that need agreement in the future e.g. subject to the
approval of, acceptable to, to be determined, to be agreed.
Avoid requirements that do not describe everything that is required e.g.
containing but not limited to, etc, as a minimum.
Avoid lists that are not all inclusive.
6.3.3 Ambiguous requirements
Use review by other persons to try and pick up ambiguities.
Avoid use of ambiguous terms e.g. and/or, any, capable, up to.
6.3.4 Realistic requirements
Use commercially achievable tolerances.
Avoid all-encompassing terms e.g. under all conditions, always, never.
Consider the likely cost for each requirement.
6.3.5 Verifiable requirements
Requirements shall be able to confirm as being met, by calculation,
inspection, demonstration or test.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 11 of 15

How or when a requirement is to be verified should only be stated if it is
appropriately prescribed in the requirements source document.
Avoid unverifiable terms e.g. maximise, minimise, adequate, suitable,
easy, user friendly, high quality.
6.3.6 Repetition
A particular requirement shall be stated in one element only (e.g. in one
standard only for each of four types of rolling stock).
6.3.7 Performance and prescriptive requirements
A performance requirement is a measurable statement of an outcome
without stating how it is to be achieved. A prescriptive requirement is a
statement of how to do something.
Performance requirements are generally preferred over prescriptive
requirements.
Prescriptive requirements may be used where there are interface
requirements (as the requirement may need to match exactly to a
standard/proprietary item), where there has been a well developed history of
doing something a certain way (as detailed in existing standards for example),
or where there is difficulty in coming up with a suitable performance
requirement.
6.3.8 Source quality
Authors are expected to reword /revise requirements taken from source
documents so that they are consistent with the approaches outlined in section
4.3 of this specification.
Do not copy unnecessary text from source materials critically review source
material
7 Document Factors
This section discusses various elements and features that are used to assist
with document control and identification.
7.1 Document Control
7.1.1 Identification
The Identification section is used to uniquely identify the document. It also
serves as a version control tool for the document.
The table comprises of the following elements:
Document Title This is the name by which the document is to be
known
Document No. This is the (Australian Standard) number under which
the document has been registered in the Document Register
Version No. The is the version number of the document
Publication Date This shows the proposed date of publication, from
which the document becomes effective

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 12 of 15

7.1.2 Preparation & Approval
The Preparation & Approval section is used to record who prepared the
document and when it was approved.
The section comprises of the following elements:
Prepared by This shows the name of the group who prepared the
standard.
Approval Date The date of the documents approval by the RISSB
Board.
7.1.3 Distribution and Change
The Distribution and Change section of the document is used to outline the
distribution and change process for the document.
These are generic clauses used in all standards refer to the template.
7.1.4 Document History
The Document History section is used to record changes to the document
after its initial publication.
This section shall have two parts:
1. Changes To Previous Version A summarised/short description of
major changes from the previous (published) version.
2. Previous Published Versions A list of the document number and date
of previous published versions, or identification of what document(s)
the standard is replacing.
8 MS Excel Document Format
8.1 Section and Clause Numbering
Each sentence within the REQUIREMENTS column shall have a unique
Section plus Clause number.
Identification of each Section of text within each standard shall be by
numbering in the form of 1, 1.1, 1.1.1 and 1.1.1.1.
The sectional numbering scheme should not exceed four levels, i.e. there
should be no numbering of the form 1.1.1.1.1 for example.
Clauses shall be identified by numbering in the form of 1, 2, 3, 4.
Clauses that are part of a list should be identified by a suffix to the list heading
text clause number in the form of (a), (b), (c) etc. Example: 5 The something
shall, 5(a)Option 1, 5(b) Option 2, 5(c) Option 3. Each list item is to be
on a separate spreadsheet row.
8.2 Location and Alignment
The main body of the standard shall be placed in the REQUIREMENTS
column.
Heading text shall be placed in the REQUIREMENTS column, each in its
own row.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 13 of 15

Clauses that are part of a list (i.e. have an (a), (b) suffix) shall be indented
in the REQUIREMENTS column.
Depending on the template being used, there will be other columns in a
standards document for other supporting information, e.g.:
TYPE
HAZARD
IC
SOURCE
BACKGROUND INFORMATION
REVIEWERS COMMENTS
IMPACT
AUTHORS RESPONSE
Text and numbers shall be horizontally left justified and vertically top justified,
except for:
Figures, Tables and Equations which shall be horizontally centre
justified,
Text in the TYPE column which shall be horizontally centre justified
and vertically top justified,
Xs in the IC column which shall be centre justified vertically and
horizontally.
Large Figures and Tables may need to be placed in a separate Appendix
worksheet, as they do not fit legibly into the standard width
REQUIREMENTS column.
Do not use Merge Cells in the spreadsheet standards documents.
Image properties shall be set within the spreadsheet to be Move but dont
size with cells right click, select Format Picture then Properties.
8.3 Font
Font for general text shall be Arial, size 10.
Heading text shall be Arial, bold.
Level 1 headings shall be upper case, size 16.
Level 2 headings shall be upper case, size 14.
Level 3 headings shall be mixed case, size 12.
Level 4 headings shall be mixed case, size 10.
Table, Figure and Equation title text shall be Arial, bold, upper case, size 10.
8.4 Colour
The column description row shall have a yellow fill.
Heading rows shall have a grey-25% fill, excluding the SECTION column.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 14 of 15

Text in the Introduction section and additional supporting information (non-
requirements) in the main body of the requirements shall have a light green
fill.
Text shall be black, except with new or changed text in a revised version
which shall be red.
8.5 Requirements Classification
8.5.1 Use of Type Column
Each row shall be classified by an entry in the TYPE column.
The permissible classifications are:
HED for headings (i.e. light grey coloured cells)
SUP for supporting information (i.e. light green coloured cells)
MAN for mandatory requirements (i.e. shall)
REC for recommended requirements (i.e. should)
Figures, Tables and Equations will generally be classified as SUP as they
will have a linked requirement pointing to them, e.g. The X shall have a Y that
complies with Table 1. This linked requirement may be any of MAN, REC or
SUP depending on the wording (in the example given would be MAN).

8.6 Interface Coordination
The AS 4292 suite of railway safety standards identify the need for interface
coordination for railway operations. For example AS 4292.3, covering rolling
stock, states in clause 2.1 that an interface coordination plan shall be
established and clause 2.2 lists some of the matters to be considered for
rolling stock operation. To assist in the development of interface coordination
plans between operators and track managers, the standards shall identify
requirements that are likely to need consideration in these plans. This will be
achieved by the Authors adding a capital X into the IC column for these
requirements.
Requirements that may need to be in interface co-ordination plans are those
that deal with issues that are not just about the document being written, but
those that may affect other users on a railway. For example, headlights would
be applicable but interior lighting would not.
8.7 Background Information
The BACKGROUND INFORMATION column can be used to contain
information which may be useful to users of the standards, for example:
Explaining the rationale of the requirement
Detailing where to obtain a referenced document (e.g. via hyperlinks)
Information which gives ways of meeting a particular requirement shall be
contained within the REQUIREMENTS column, but shall be in light green
filled cells.

Document Style Guide - Standards

ADMIN 3.4 Document Style Guide
Standards V3
August 2012 Page 15 of 15

8.8 Single, simple requirements
There shall be one sentence per row in the REQUIREMENTS column cells
of the spreadsheet document.
There shall be one requirement per sentence.
Use and only when necessary, i.e. create multiple requirements if the
requirements are not strictly interdependent.
Keep each requirement as short and simple as possible.
Remove explanations out of requirements (e.g. text starting with so as to...).
This text can be placed in the Background Information column if desired.



9 Record Requirements
The following records are retained as evidence of compliance to this
procedure:
MS Content Update
Review Records