ATP Style Manual 01

8/14/2019 ATP Style Manual 01

1/47

ATP Style Manual

Page 1

PREFACE

Advanced Technical Publications (ATP) aims to develop world-class site or organisation-

specific technical and training documentation for industry. We want ATPs name to become

synonymous with high quality documentation that exceeds all others in presentation,

readability and technical accuracy. Every document that we produce will remain at large for

many years and will bear testimony to the effort, or lack of effort, that was expended in its

development. It is important that we strive to for excellence in every document that we

produce. It is also important that we help to build our corporate image as documentation

specialists by achieving consistency in our techniques and methodology across a range of

Technical Writers and a range of projects. We achieve this by using high quality photographs,

graphics, cartoons and layout methods.

The purpose of this manual is to assist writers in achieving consistency, to point out some of

the most common writing problems and to answer the common questions. You must

remember that no style manual can ever provide the solutions to all writing problems. When

writing or layout problems occur to which there seems to be no ready answer, it is the

writers job to arrive at a workable solution. The fact that you are employed as a Technical

Writer means that, by definition, you are expected to know the basics of spelling, syntax and

grammar. Grammar and spelling are covered in the manual but not at great depth.

It is also important to remember that the English language is organic it is prone to change.

What was fashionable this year may not be so in years to come. As well as this, the manualmay have been deficient in certain areas in the first place. Accordingly, all ATP personnel are

invited to offer suggestions for changes to the ATP styles or other amendments and additions

to this manual. However, having invited comment we should also stress the adage: if it aint

broke, dont fix it.


2/47

ATP Style Manual

Page 2

TABLEOF CONTENTS

TOPIC ONE STYLE BASICS ................................................................. 3

INTRODUCTION ................................................................................................................................... 3

COLOURED TEXTS ................................................................................................................................ 4

BULLET POINTS .................................................................................................................................... 4

WORD CHOICE ................................................................................................................................... 7

SENTENCE STRUCTURE ...................................................................................................................... 10

PARAGRAPHS ...................................................................................................................................... 13

PUNCTUATION ................................................................................................................................... 13

SPELLING ............................................................................................................................................ 24

STYLISTIC EMPHASIS ............................................................................................................................ 26

DEALINGWITH NUMBERS .................................................................................................................. 27

PHOTOGRAPHS ................................................................................................................................... 29

ILLUSTRATIONSAND GRAPHICS ........................................................................................................... 32

CARTOONS

......................................................................................................................................... 33CLIENTS FORMSAND OTHER DOCUMENTS ...................................................................................... 34

PROOF READING ................................................................................................................................ 34

ABBREVIATIONS .................................................................................................................................. 36

WORKING DRAFTS ............................................................................................................................ 36

SUMMARY ........................................................................................................................................... 40

TOPICTWO QUALITY BASICS .......................................................... 41

INTRODUCTION ................................................................................................................................. 41

WHATISA STANDARD ATP TRAINING PACKAGE? .............................................................................. 41

THE DEVELOPMENT PROCESS ............................................................... 43

VISION/MISSION STATEMENTS................................................................ 47


3/47

ATP Style Manual

Page 3

TOPIC ONE STYLE BASICS

INTRODUCTION

Layout and appearance go hand-in-hand with graphics, illustrations and cartoons. This is the

area where ATP can excel and where we should always strive for high standards. There is a

perception that anyone with some technical background can write a technical manual. Our

main weapon to overcome this perception lies in the superior appearance of the

documentation that we produce. If we cannot make it stand out from the rest, no-one will

ever know that the content we include is also superior.

It is difficult to prescribe hard and fast rules about layout but the general topics covered in

this style manual should help Technical Writers to develop documentation that stands out

from the rest.

FONTS

It is important to use font choice carefully. If poor choices are made, the document can

become next to unreadable. A survey (Colin Wheildon) has shown that in 67% of cases,

readers achieve good comprehension of a given text which has been printed in a serif font.

On the other hand, of the same group of readers only 12% achieved a good level ofcomprehension when the text was printed in a sans serif print. Generally speaking, serif type

fonts are more readable as body text and therefore the information conveyed by them is

more accessible than when presented in some other form. The following examples show the

general fonts that we use at ATP for A4 documentation.

EXAMPLE OF HEADING Arial font at 24pt bold, caps.

EXAMPLEOF SUB HEAD 1 Arial Narrow font at 21pt bold, small caps.

Example of Sub Head 2 Arial Narrow font at 16pt bold.

Example of Sub Head 3 Arial Narrow font at 14 point bold.

Example of Sub Head 4 Arial Narrow font at 12 point italics.

Example of Body Text Times New Roman font at 12pt.

Example of Photo Caption Text Arial Narrow font 10pt font at 10 point sizing.


4/47

ATP Style Manual

Page 4

COLOURED TEXTS

Generally, coloured texts are less clear than plain

black ink. A page of red or blue is not something that

you want to see. Some colours show up particularly

badly in printed matter (eg. yellow). Therefore, we

avoid the use of colour in our finalised documentation.

Having said that, coloured text can be useful to draw

the layout persons attention to a writers direction.

For example:

Insert photo OD-3 P17: The Tails Leach Thickener.

Please insert diagram # 003 here

Colours can also work well when they are used in headings and subheads. However, it isimportant to remember that colour printers are not yet universal and, in many cases, are

very expensive to use. Your customer may not have the option of printing in colour.

Having said all of the above, coloured photographs are a very useful part of the way we

develop documentation at ATP. They serve the dual purpose of providing extra detail and

explanation while dressing up the document.

BULLETPOINTS

We frequently use bullet points and

numbered lists in the work that we do at

ATP. It is important that we are

consistent in their use. It is also

important to make sure that the

hierarchy is identifiable. An example of

the use of bullets may be as follows:

This is an example of a first order bullet point:

an example of a second order bullet point

an example of a second order bullet point

an example of a second order bullet point.

This is an example of a first order bullet point.

This is an example of a first order bullet point.


5/47

ATP Style Manual

Page 5

When using bullet points, it is also important to know when to use capitals at the beginning

of the point and when to use full stops at the end of the point. The following rules will cover

most situations:

If each bullet point within the list is a discrete sentence, then each should carry a capital

first letter and a full stop. If the bullet point list commences with part of a sentence and the sentence is completed

by each subsequent bullet point, only the opening clause carries a capital and only the

last clause in the sentence carries a full stop. Notice that it is possible to have more than

one sentence in a bullet point if that is what is necessary to explain your point.

The following examples should help to clarify the bulleting situation:

A set of bullet points could be a simple list consisting of:

letters

words

punctuation marks, such as:

commas

semi-colons.

numbers

measurements.

A set of bullet points could be more complex by carrying a sequence of concepts or ideas,

such as follows.

Before passing through the security gate, you must ensure you:

complete your site induction

complete your area induction

fill in the visitors form

obtain and wear the correct PPE for the area

obtain the site managers authorisation

place your tag on the visitors tag board.

There are two important things to notice here. The first is that only one full stop is used in

the entire sequence and the second is that all the bullet points are parallel. The idea of

parallelism means that every bulleted clause can be referred back to the opening clause and

be read as a proper sentence.


6/47

ATP Style Manual

Page 6

NUMBERED LISTS

The following procedure for using a computer is an example of a simple numbered list:

1. Switch on the computer.

2. Open the application.

3. Open the file you need.

4. Make your changes.

5. Save the changes.

6. Shut down the document.

7. Shut down the application.

8. Shut down the computer.

Notice that these are all imperatives and the subject is implied. These constitute fullsentences and, therefore, each must start with a capital letter and finish with a full stop.

Once again, more than one sentence could be used in this format. You can also use multi-

level versions of numbered lists. You can see an example of a multi-level numbered list

below:

This lesson will examine the main components of the vehicle in the following order:

1. body

2. chassis

3. engine

a. lubrication system

i. oil reservoir

ii. oil pump

iii. oil filter

b. fuel system

i. fuel tank

ii. fuel pump

iii. fuel filters

c. cooling system

i. radiator

ii. coolant

iii. coolant pump

4. transmission

a. transmission lubrication

5. differential

a. differential lubrication.

As you will notice, none of the numbered points is capitalised and only the final point

receives a full stop.


7/47

ATP Style Manual

Page 7

WORD CHOICE

Whenever you write anything you need to make sure that you are aiming the language at the

right level to suit your readers. If you write at a high level, you run the risk that your

audience will not understand what you are trying to convey. If you write at a level that is too

low, you may alienate your readers by insulting their educational levels. In either case, your

readers will lose interest and what you have written will be lost to them.

So the first step in writing is to know the audience for

which you are writing. ATP predominantly develops

documentation that will be read by blue-collar workers. A

fact of life is that people who do blue collar work often do

not possess high level reading and comprehension skills.

This is not a comment on their intelligence levels or their

abilities. It is merely an acknowledgement that many of

these people have chosen not to make high levels ofacademic education a high priority in their lives.

TWO-CENT WORDS

The simple rule to remember is to use two-cent words rather than two-dollar words. The

following list shows a small sample of two-dollar words that have a two-cent equivalent or

near-equivalent:

Abundance lot; many

Automobile car

Commence begin

Confectionary effigies of wet-skinned, amphibious

reptiles of the croaking type chocolate frogs

Enormous large

In view of the fact because

Initial; initially first

Initiate start; begin

Magnitude size; capacity; etc

Salubrious healthy

Utilise use

Vestigial remaining.

Whenever you read (books, newspapers, magazines, other technical documentation), build a

collection of words to use and words not to use.


8/47


9/47

ATP Style Manual

Page 9

NON-DISCRIMINATORY LANGUAGE

We must not use discriminatory language. By being thoughtful about what you write you

should be able to avoid discriminatory language altogether. Fortunately, you can avoid

discriminatory language much more easily as a Technical Writer than you could, for example,

as a journalist. Some of the ways in which we can be discriminatory are as follows:

on the basis of gender

on the basis of race

on the basis of age

on the basis of religion

on the basis of educational levels

on the basis of physical ability or disability

on the basis of appearance

on the basis of dress/fashion

on the basis of position within the organisation

and there are many other ways in which we can be discriminatory.

Probably the most commonly used discriminatory language refers to gender. In the not-too-

distant past, it was common for non-fiction books to refer to males whenever an example or

anecdote was called for. This is no longer acceptable. If your writing calls for a mention of

the pronoun for the third-person, you must balance the possible sexism by including bothgenders. For example:

The operator must always conduct a pre-start inspection. He/she should start at the

base of the operator steps and work around the dozer until all points have been

inspected and passed as satisfactory. Any operator ignoring this procedure could find

him/herself in a dozer that is not performing correctly.

The example above is closer to correct English than the use of plural which some writers

use. Clearly, the use of the plural third-person usages (they and them) would be definitely

out of place in the above text.

REMEMBER!

Your job is to communicate complex technical issues in ways which

are easy to read and understand.


10/47

ATP Style Manual

Page 10

SENTENCE STRUCTURE

Use the information in the following comments to help with your general sentence structure.

SENTENCE LENGTH

There is very little point in devising sentences that are so long that the point is missed by the

time the reader reaches the end. Newspapers generally limit the size of their sentences to

about 30 words. Hemingway, limited his sentences to around twenty words. In most cases if

you are exceeding 30 words, your sentences are probably too long for a technical or training

document. There are exceptions to the rule so do not try to laboriously follow it in every

situation. However, try to keep your sentences short and to the point.

COMMA SPLICES

The comma splice is often related to sentences that are too long.

If your sentences are regularly exceeding ideal length and you

are using a lot of commas, you are probably creating comma-

splice sentences. A comma-splice sentence is generally made up

of two or more sentences presented as one by the expedient of

incorporating additional commas.

The following is an example of a comma splice sentence:

The haultruck is powered by a V16 Detroit diesel engine, the power from the engine is

transferred to rear wheels via a seven-speed automatic transmission and a heavy duty

differential.

This is actually two sentences that have been incorrectly joined by the placement of a

comma after the words diesel engine. The simple way to fix this problem is to replace the

comma with a full stop and to capitalise the word the as the start of a new sentence.

REMEMBER!

If your sentences are consistently too long, make sure that you arenot using comma splices.


11/47

ATP Style Manual

Page 11

ACTIVE VERSUS PASSIVE SENTENCES

One of the common problems with technical

writing is the use of passive sentences. The

use of passive sentences generally means that

text is going to be excessively wordy andmore difficult to read and understand.

The following show simple examples of active

and passive sentences:

Passive On the mat the cat is going to sit.

Active The cat is going to sit on the mat.

The following show more complex examples of active and passive sentences:

Passive On the front, left-hand side of the haultruck is located the manual up-down,

stair control.

Active The manual, up-down, stair control is located at the front, left-hand side of the

haultruck.

The basic structure of the two types of sentence can be illustrated as follows:

Passive object verb subject or object subject verb

Active subject verb object

In either of the two passive cases the object has been allowed to be placed at the beginning

of the sentence.

Another version of the passive sentence is the expletive construction. This is where

sentences are begun with word combinations such as: There are; It is. In some cases

this structure is almost unavoidable. However, such sentence openings can be changed for

the better with just a little thought. See the following examples:

Expletive construction There is a requirement for all personnel to carry a respiratorwhen entering this area.

Improved version All personnel must carry a respirator when entering this area.

Expletive construction It is a difficult situation because we will be forced to purchase

more equipment to cope with the extra demand.

Improved version We have a difficult situation which will force us to purchase more

equipment to meet the extra demand.


12/47

ATP Style Manual

Page 12

To avoid passive sentences, work out what or who is acting as the doing agent (the subject)

and make sure that he/she/it is placed before the verb. This will generally lead to active

sentence construction.

SENTENCE FRAGMENTS

Technical writers often get so entrenched in the subject matter that they forget to check

what they have written. Because of this they often have difficulty in identifying sentence

fragments. A sentence fragment is a series of words that at first glance looks like a sentence

but when read in isolation, it becomes clear that it lacks a verb or a subject. A sentence

fragment is normally embedded between a couple of normal sentences so it is somewhat

disguised by its proximity to them. The following shows an example of a sentence fragment.

Eleven Caterpillar 793 haultrucks are used to transport the run of mine ore from

shovels 1, 5 and 7 to any one of the three gyratory crushers. Four to crusher 1, four tocrusher 5 and three to crusher 7. The haulage system can be altered to suit current

conditions in the mine and the status of the individual crushers.

As you can see, the sentence fragment above is highlighted. The reason it is a sentence

fragment is because it contains no verb. Avoid this type of mistake by carefully reading what

you have written.

Because sentences are infinitely variable, it is impossible to prescribe what an ideal sentence

should look like. As a Technical Writer you have to be able to gauge that for yourself. In

order to write readable, meaningful sentences, you need to know exactly what it is that you

are trying to say. If you do not have a clear goal in mind, your sentence will invariably turnout to be nonsense.

The ultimate test of a sentence is to determine whether or not it is readable and makes

sense. When you proof-read your own text, if there are sentences that leave you unclear

about what you originally meant, there is no hope for your reader. Careful proof-reading of

your own work is the best way to find and correct your own mistakes. An important point

to remember is that you will never be able to proof-read satisfactorily on the screen you

should always print out and proof-read a hard copy.


13/47

ATP Style Manual

Page 13

If you want to find out more about more about words and

sentence structure, you can use the following texts:

The Professional Writing GuideWriting Well and Knowing

Whyby Roslyn Petelin and Marsha Durham

The Little, Brown Handbook by HR Fowler; JE Aaron and

D Anderson

Handbook of Practical English by RC Cornish

You can also use a good dictionary, a thesaurus and/or

an English Usage book to help you to find words and

structure sentences. Finally, the computer that you are using

carries a built in thesaurus which can be useful in the search for words.

PARAGRAPHS

Once you have selected the words, structured the sentences, you need to determine how

the paragraph fits together. Roslyn Petelin and Marsha Durham (The Professional Writing

Guide) suggest that a paragraph should be: complete; unified; ordered. All ATP Technical

Writers are urged to read the chapter in this book on the construction of paragraphs.

In short, a paragraph should contain all the necessary information to make a point or series

of points. All of these points should be from the same or a similar perspective and carry a

similar tone. The information contained in the paragraph should be presented in a logical

order and the information should be complete.

REMEMBER!

A break for a paragraph should be decided in relation to the

information it contains not in relation to the paragraphs size.

PUNCTUATION

This section will look briefly at the basics of punctuation. Punctuation is used to guide thereader throughout he text and show him or her how the writer intends a given piece of text

to be read. The main point about punctuation is that it is most often correct when it is not

noticeable. If you proof-read a document and do not notice the punctuation, the chances

are that it is punctuated correctly.


14/47

ATP Style Manual

Page 14

COMMAS

The comma is probably the most versatile and widely used punctuation mark in the English

language. It has a number of purposes which include:

separating the discrete items in a list within a sentence

separating adjectives within a sentence

separating an aside within a sentence

separating discrete clauses within a sentence.

Separating Discrete Items

The following sentence is an example of the separation of discrete items in a list within a

sentence.

Before you start writing a document, you must set the scope of what you will write,

research your subject, obtain the necessary photographs, and decide in what format your

document will be written.

NOTE!

In this case, the comma before the word and is appropriate.

REMEMBER!

If the list contains more than three or four items, consider using

bullet points to make the content of the sentence clearer.

Separating Adjectives

Adjectives are the describing words that are used to qualify

distinctions about a given noun. When you need to use

two or more adjectives, you should use commas to separate

the discrete adjectives in the string. For example:

The square, green, 40-litre oil tank carries the systems

hydraulic fluid. Its level must be checked on a daily basis.

REMEMBER!

Adjectives are used to modify nouns while adverbs are used to

modify verbs.


15/47

ATP Style Manual

Page 15

Separating an Aside Within a Sentence

This is a fairly common use for the comma. In this case, commas are used in a similar way to

brackets. You must remember that generally two commas (known as comma pairs) will be

required. This requirement can be negated if the aside is placed at the end of the sentence.

However, such structure often conveys the feeling that what comes after the comma issimply an afterthought. At best it is an unwieldy construction.

The following sentence shows an example of the use of comma pairs with the aside and the

commas highlighted:

The capacity of the centrifuge, running on material containing 40% moisture, is

approximately 80 TPH.

The same aside could be placed at the end of the sentence in which case there would only

be a need for one comma.

The capacity of the centrifuge is approximately 80 TPH, running on material containing

40% moisture.

As you can see the second version is somewhat unwieldy and would not be the preferred

method of delivering this information.

Separating Discrete Clauses

Within a Sentence

This is the area where we frequently use commas. This is also

the area where poor teachers of English have told their

students that they should place the comma where they would

pause in normal speech. This advice is INCORRECT. The

comma is used to indicate that an idea or a notion has been

expressed within the sentence and that we are now going to

move on to the second idea or notion. It can also be used to

avoid confusion in the meaning of a sentence. For example:

After they met the union and the management decided to continue the negotiations.

After they met, the union and the management decided to continue the negotiations.

You should be able to discern the difference that the comma has made in this case.

The following sentence shows an example of using a comma to separate a discrete clause:

Around 3 billion years ago, the big bang signalled the beginning of the universe.


16/47

ATP Style Manual

Page 16

APOSTROPHES

The apostrophe has two main uses. The first is to denote

ownership or possession and the second is to denote an

abbreviated word. The following sections provide brief

explanations and examples of both.

Ownership

Ownership is normally indicated by adding an

apostrophe and the letter S. The typical example

below shows that the person with the name Jim has

ownership of the object.

Jims car.

If we were to use Jims given name of James ownership is shown is a slightly different way.

For example:

Jamess car.

There are more variations involved in the usage of the possessive apostrophe but the above

should suffice for most technical writing requirements.

When we are dealing with a plural, the apostrophe is placed after the final S. The following

two examples illustrate the methods for dealing with possessive plural and singular

apostrophes:

Plural The miners cap lamps and self-rescuers are left in the bath house at the end of

the shift (several miners so therefore several cap lamps and self-rescuers).

Singular The miners cap lamp and self-rescuer are left in the bath house at the end of

the shift (single miner so therefore only one cap lamp and one self-rescuer).

Apostrophe Abbreviations

Generally, apostrophe abbreviations should not be used in technical documents. Technical

documents are formal and you can reinforce the formality by not using abbreviations. This

rule does not apply to the text of videos and multi-media voice-overs. Abbreviations are

then used in preference to the formal version. Some examples of apostrophe abbreviations

include:

dont

wont

isnt

wasnt

didnt

its.


17/47

ATP Style Manual

Page 17

Inappropriate Use of Apostrophes

The most common inappropriate use of

apostrophes is to place them where

they are not needed. The two most

common errors are:

Using an apostrophe to indicate the

possessive when the word itself is

automatically possessive. For

example:

its WRONG

yours WRONG

theirs WRONG

There is no need to use the apostrophe in these examples because the words themselves

indicate the possessive. In any case, the word its is the abbreviation of the words it is.

Using an apostrophe when pluralising an abbreviation. For example:

TWs WRONG

VCRs WRONG

DVDs WRONG

The apostrophe is not needed here unless the subject of the abbreviation is possessive.

Several Technical Writers (TWs) are not necessarily possessive. If they are possessive, the

apostrophe is appropriate.

BRACKETS

Brackets are used when you need to either make an aside or say something that relates to

the surrounding information but which does not need to be stated directly. They can also be

used to show the abbreviations that you are going to use throughout the document. Thefollowing sentences show examples of the use of brackets:

When you write a training manual (or any other type of formal or technical document),

ensure that you use correct terminology.

The Advanced Technical Publications (ATP) style manual is ready for use.


18/47

ATP Style Manual

Page 18

COLONS

The colon is used to announce a clause, a list or other

information. The following examples illustrate the use of the

colon.

At the end of the shift, you should do the following:

complete the end-of-shift report

ensure the incoming shift knows the location of all mobile

equipment

ensure the in-coming shift has details of any breakdowns

ensure that all out-going personnel remove their tags from the tag-board.

There are three steps in the start-up process for the dozer:

1. Carry out a full pre-start inspection.

2. Ensure that the park brake is engaged, the transmission is in neutral and the

ground engaging tools are lowered.

3. Sound the horn, start the engine and allow it to run at an idle until it is warm

enough to take a load.

In a technical document, there is no reason why a colon should not be used at the first and

second level of bullet points. The following example illustrates the use of the colon at two

levels:

The transmission consists of three main sections:

a dry single plate clutch

manual transmission which includes:

five forward speeds

one reverse speed

transfer gears for four-wheel drive

hi pressure oil pump

limited slip differentials on front and rear axles.

REMEMBER!

The old method of using a colon with a dash (:-) is now considered

to be archaic. The dash is no longer considered necessary.


19/47

ATP Style Manual

Page 19

SEMI-COLONS

The semi-colon is very rarely used in technical writing. It has three main purposes:

The first is to join two separate ideas that have a commonality. In this instance the semi-

colon is used in a place where you could use a full stop. For example:

The Technical Writers at ATP are the best available; they are highly experienced and have

extensive technical backgrounds.

The second is to show the separation point of two ideas that are separated by a con-

junction (however, nevertheless, etc). The following example illustrates this technique:

The Technical Writers at ATP are the best available; however, they can only stay on top by

constant attention to detail.

The third purpose for the semi-colon is to separate a string of items which have internal

punctuation. For example:

The claim to being the best in the business is legitimate because ATP Technical Writers

pay painstaking, meticulous attention to detail; understand the basics of mining, minerals

processing and engineering practices; and are committed to the development of high

quality, world-class training and technical documents.

FULL STOP

The full stop has one major purpose. That is to signify the end of a sentence. The placementof full stops varies to some extent the conditions that surround it at any given time. The

conditions caused by bullet points, tables, headings and sub-headings, and brackets may make

a difference to your placement of the full stop. These issues are dealt with at each of the

relevant sections. One important point to remember is to ensure that the full stop must be

followed by a double space or by an en or em space.

As a point of interest, at ATP we strive to use open styles for punctuation and layout so the

use of full stops to indicate abbreviations is not used. If the presence and meaning of anabbreviation can not be made clear, do not use it.


20/47

ATP Style Manual

Page 20

ELLIPSIS

The ellipsis is made up of three full

stops placed in a row. It is used to

indicate that there was more to be

said but it is not going to becovered in detail at this juncture.

The ellipsis is rarely used in

technical documentation. The

following example illustrates a

typical use for an ellipsis:

At the end of the day, the workers go home and

The detail of what the workers do at home is not important and can safely be left to the

readers imagination.

The ellipsis can also be used to indicate where words have been left out of a quotation.

There is very little of a technical nature that we would want to leave to the imagination or

leave out; hence, the ellipsis is rarely used in technical documentation.

QUOTATION MARKS

Quotation marks have two main purposes:

To indicate that a passage of text has been quoted directly from either a person or a

text.

To indicate that a word or phrase has been coined within a sentence.

The following shows an example of each:

The shift superintendent said, We must follow the manufacturers instructions when we

start up the dozer.

The use of the quotation marks in this instance should be self-explanatory.

We can use the manufacturers information to fill in any gaps in the training manual.

In this case, the quotation marks are used to highlight the fact that the metaphor fill in any

gaps has been coined to indicate that the training manual lacks some information which can

be obtained from the manufacturer.

An important point about quotation marks is that two versions are available: single quotation

marks (single quote marks) and double quotations (double quotation marks).


21/47

ATP Style Manual

Page 21

In normal circumstances, single quotation marks should be used. Double quotation marks

should be reserved to indicate a quotation within a quotation. The following example

illustrates the use of a combination of single and double quotation marks:

The shift superintendent said, We must follow the manufacturers instructions when

starting up the dozer. The Caterpillar manual says: Depress the throttle, engage theinjector heater for 10 seconds, turn the start key and release the key when the engine

fires..

A final point for dealing with quotations is that the correct way to deal with a quotation that

is greater than forty words is to indent the quoted text: The following example illustrates

this point:

The standard ATP promotional letter says:

The team atAdvancedTechnical Publications can demonstrate a very successful track

record as developers of excellent technical and training documentation for both theAustralian and overseas markets. As a result of our experience, we have devised

innovative methods of presenting complex and technical information so that it is

easily learned and remembered even where language and literacy may be barriers

to learning.

You can use quotation marks within an indented section of text to indicate a quotation

within quotation.

DASHES

At ATP we make significant use of

the dash. To distinguish dashes

from hyphens, we use the em

dash (). The purpose of the

dash is to show a change of tone,

new thoughts or as parentheses

particularly when commas are

used within the parentheses.

The following examples illustrateeach of the above:

Change of tone. Good writing is something that most intelligent people can enjoy

the trouble is that this is not good writing.

New thoughts. We need to hone our writing skills by practising what we have learned

we also need to practise our typing to increase our speed.

Parentheses. The drive train of the haultruck engine, transmission, tail shaft and

differential must be regularly checked for oil leaks in order to prevent serious

damage.


22/47

ATP Style Manual

Page 22

HYPHENS

Hyphens are distinctly different to dashes in both appearance and purpose. The hyphen (-)

is considerably shorter than an em dash ().

The purpose of the hyphen is to join two words together to create a third. In doing this, insome cases, the hyphen reduces possible confusion. For example, there is a difference

between:

a man-eating fish and a man eating fish.

Some further examples of this use of the hyphen include:

pre-start inspections

walk-around inspections

belt-drive

the drive-it-until-breaks maintenance program

english-speaking person

diesel-driven generator

Hyphens are also used to is when figures are involved. For example:

12-year old engine

three-week turnaround

14/7-day roster

There are some composite words that are now readily accepted. These include

turnaround

desktop

haultruck

shutdown.

In many cases, you will

have to be guided by

house style and by your

own common-sense.


23/47

ATP Style Manual

Page 23

SLASH

The slash is commonly used to show the date. For example:

20/08/02.

Remember that the American usage reverses the order of the day and month. This can be

important when you are using computers which often follow the American methodology.

The slash can also be used to indicate that there is an option within the sentence. For

example:

The trainee must undertake an assessment in real/simulated working conditions.

CAUTION!

Never try to use the slash in computer file names. The slash is oftenused in computer technical protocol so its use is not advisable in

file names.

EXCLAMATION MARK

The explanation mark should only rarely be used in technical writing. The only suitable place

for an explanation mark to be used is in conjunction with a prompt. At ATP we use the

following prompts in our documentation:

Danger!

Warning!

Caution!

Note!

Important!

Remember!

Informational prompts are discussed in a later section of this manual.

QUESTION MARKS

Similarly to the exclamation mark, there is

generally only one suitable place for question

marks to be used in technical documents

in the assessment instruments. If you dont

know when to use a question mark, hand inyour resignation right now.


24/47

ATP Style Manual

Page 24

CAPITALISATION

Basically, we should strive to minimise the use of capitalisation on the page. Obviously, a

capital should appear at the beginning of a sentence. Capitals should also be used when we

have abbreviated a term (ATP, SES, CPU). All proper nouns should be capitalised.

Equipment items (draglines, dozers,), generalised

positions (office manager, technical writer) and areas

(mill area, flotation area), should not be capitalised.

Capitals are used to ensure that a given

word stands out from the rest of the text.

If they are only used when necessary,

they will maintain their importance. If

they are overused, the page becomes

difficult to read and capitals lose their

importance.

The following sentence illustrates the

overuse of capitals (unnecessary capitals

are highlighted):

The Operators load Haultrucks by the Shovel at one of the Loading Bays in the Lower,

East-End Pit on every Monday, Wednesday, Friday and Sunday and by the Excavator in the

Lower West-End Pit on every Tuesday, Thursday and Saturday.

SPELLING

Spelling is very important. Any misspellings in a technical document will very quickly cost the

author his/her credibility. Make sure that every word in your documentation is correctly

spelled.

AMERICAN SPELLING

The first thing to say about spelling is that

we use Australian standards not American.

So, words spelt as follows should be avoided:

color WRONG

labor WRONG

sulfur WRONG

An acceptable exception to this rule is when

we are developing material for an American

concern. For example, in the case of

Freeport, we used all American spelling andAmerican paper sizes in every document we

produced on their behalf.


25/47


26/47

ATP Style Manual

Page 26

STYLISTIC EMPHASIS

The are three ways you can use styles to emphasise items within your text. These are:

bold text

italicised text

underlined text.

BOLD

In ATP documents, bolding is always used in the text for the informational prompts. It can

also be used to indicate important clauses or sentences throughout the text. Under certain

circumstances, a single word can be bolded to highlight its importance; however, this

technique can easily be overused. A number of individual bolded words on a page are all

screaming to be heard and none of them can be heard above the overall murmuring burble.

ITALICS

Italics are generally reserved for the name of a publication, movie, or a TV program. For

example:

The Guide to Mining Best Practice

The Caterpillar 793C Training Program

Media Watch

Terminator Four I am Back

Notice that the definite article (the) is regarded as part of the title.

ATP uses italics for its prompts; however, this is a special case to make something that is

particularly important jump off the page at the reader. ATP also uses bold and italics in theword processed version of its name:

AdvancedTechnical Publications Pty Ltd

Once again this is for a special purpose and would not be used in general text applications.


27/47

ATP Style Manual

Page 27

UNDERLINING

Underlining is a leftover from typewriter days.

When we only had typewriters, it was one of the

main of methods of highlighting a given piece of

text. This is not the case since the advent ofword processors. The word processor has

effectively made the underline redundant. In any

case, the appearance of underline is not

particularly pleasant. Use underlining sparingly

avoid it all together unless it is absolutely

necessary.

Apart from informational prompts, never use two forms of highlighting on the same text it

makes at least one of the methods redundant. Bolding and underlining a given piece of

text is particularly uglyadding italics makes things even worse and adding another

style technique such as a colour makes it worse again.

DEALINGWITH NUMBERS

It is very simple to deal with numbers. For straight

numbers, the basic rule is that numbers up to ten

inclusive are written in full and numbers above ten arewritten in figures. There are some allowable variations

when dealing with hundreds of thousands, millions and

billions. The following examples show how it should be

done:

one to ten should be written in full

11 to 999,999 should be shown in figures

one million and beyond should be written in full.

NOTE

When using figures, a comma should be placed to separate the

hundreds from the thousands, tens of thousands and hundreds of

thousands (once the number requires more than four digits).


28/47

ATP Style Manual

Page 28

TIME

Time can be dealt with in two ways. The twenty-four hour clock calls for a four-digit number

and the abbreviation for hours. For example:

1230 Hrs indicates half an hour past midday

2345 Hrs indicates a quarter of an hour to midnight.

The second method to deal with time is to use the twelve-hour clock. To express a time, this

method uses two sets of figures separated by a colon with a suffix indicating whether it

refers to before or after midday. The numerator before the colon can be either a single or

double digit. The numerator after the colon is always a double digit even if both are zeros.

For example:

10:30am

9:45pm

11:00am.

DEALING WITH MEASUREMENTS

Measurements are relatively easily dealt with if a few

simple rules are applied. Because we use the

metric system, capacities, lengths, weights, etc

should always be quoted in metric measurements.

It is, however, acceptable to place the imperialequivalent in brackets after the metric version.

For example:

220 tonnes per hour (242.5 TPH)

27.5 metres (90.22 feet)

205 litres (45 gallons).

The important criteria is that measurements

should not be mixed. For example do not start off

talking about metres and then suddenly change tomeasuring in yards.

It is acceptable to use abbreviations for measurements; however, you must be sure that the

reader will be clear about your intended meaning. The best method to do this is to clarify

what you mean the first time you introduce the measurement with the abbreviation.

Thereafter, consistently use the abbreviation for the remainder of the section, chapter or

topic. For example:

220m (metres)

24kg (kilograms)

67kms (kilometres).


29/47

ATP Style Manual

Page 29

The abbreviation should be introduced again if you have moved on to a new topic or

chapter.

The danger is that various abbreviations can be confused (M = mega, M = Miles, m = metre,

mm = millimetre). As long as you avoid confusing the reader, there will be no problem. Use

the full version of the word rather than the abbreviation if there is ever any possible doubtabout what you mean.

REMEMBER

In our documentation, it is our job to make issues clear and provide

answers not to confuse and raise questions.

PHOTOGRAPHS

Our use of photographs, graphics and cartoons sets us aside from our competition.

Therefore, the quality and placement of photographs in ATP manuals is critical. The factors

that affect photographs are:

quality of the original photograph this includes:

composition

lighting

ability to identify criticalcomponents

callouts used in the photographif any

portrait or landscapeorientation

relevance of the photograph tothe text

caption format and relevance.

Typically our photographs are placed down the right-hand side of the page. The orientation

that fits best on to an A4 page is landscape. However, there are times when the best

photograph of a given subject is in portrait. Ensure that you use a balanced mix of landscape

and portrait photographs in the development of your manuals when you need to include

portrait orientated photographs. Several portrait photographs in a row takes away from the

appearance of the manual. Wherever possible, photographs should be cropped in a 4:3

(landscape) or 3:4 (portrait) ratio using a photo-editing software, eg. Photoshop.


30/47


31/47


32/47

ATP Style Manual

Page 32

ILLUSTRATIONSAND GRAPHICS

Illustrations and graphics can include:

diagrams drawn by ATPs graphics department

screen dumps from on-site computer systems

scans from manufacturers manuals (if of sufficiently high quality)

diagrams provided from on-site (if of sufficiently high quality)

The first thing to say about graphics and illustrations is that we have an artwork team which

handles all the graphics and artwork that is necessary for our publications. If you wish to

have something drawn up, submit it to the graphics team as a sketch on paper. We do notwant Technical Writers wasting time drawing diagrams in Word, Corel Draw or some other

program. We have a given format and a library of graphics which we go to some length to

maintain. If Technical Writers are drawing their own diagrams, we will lose track of the library,

we will lose control of the quality of graphics and Technical Writers will not be doing what

they are paid to do. Besides this, the artwork team runs the risk of losing its jobs which

could reduce the long-term professionalism of the company.

IMPORTANT

Unless we are using artwork sourced from our clients, the ATP

graphics team must do ALL of the artwork that is to be included in

ATP documentation.


33/47

ATP Style Manual

Page 33

Our use of graphics is one of the areas where we can really show the customer that they

are receiving something that they cannot get elsewhere. In many cases, we can convert a

process, idea or concept into an illustration and make a complex situation easy to

understand. To do this takes thought on the part of the Technical Writer.

If you are having difficulty understanding something, the chances are that other people willhave the same difficulty. It is at these times that you should be thinking about having a

graphic done to make the explanation clearer. The content of the graphic or diagram may not

be immediately apparent but part of your job as a Technical Writer is to come up with the

content. In other words, if no diagram exists, design one and ask the graphics department to

draw it.

Ensure that the graphics you include are at a high enough quality for ATP standards. Using

poorly drawn or multi-photocopied diagrams obtained from site is not going to be acceptable.

ATP has a graphics and art department that produces world-class graphics and artwork.

Make sure that you use it to its best advantage.

REMEMBER

Our use of graphics and illustrations sets us apart from our

opposition. There is a belief that writing can be done by anyone

with some kind of technical background. Our use of artwork shows

that, while this may or may not be true, very few organisations can

develop the overall package at the quality ATP achieves. Please bear

this in mind in all projects that you undertake on behalf of ATP.

CARTOONS

Similarly to graphics and illustrations, cartoons

are an important part of the work we do here

at ATP. Cartoons can be used to highlight

poor practices, good practices, unrealistic

situations and for a host of other purposes.

Once again, it is important that the quality is

kept at a very high standard. As with

everything to do with ATP we have tried to

improve the quality as we progress. Thecartoons that we use today are at a higher

standard than they were when the company

was formed. If you need a cartoon which has

already been drawn but the quality is not up

to standard, have the cartoonist re-draw it and

make sure that it is what is needed.

An important point to remember with cartoons and, to a lesser extent, with graphics, is that

it is very noticeable when the same piece of artwork appears several times within the one

document. Avoid using a given cartoon more than once in the one training manual.


34/47


35/47

ATP Style Manual

Page 35

correct headers and footers

correct pagination

correct headings and subheadings.

While you should take ownership of the text, do not become carried away with making

changes. Be aware of the difference between making subjective changes and makingabsolutely necessary changes. Stylistic writing differences, differences in subject order,

may not reduce the overall effectiveness of the document and so, therefore, are not

worth changing. Remember, if it aint broke, dont fix it.

Never knowingly allow a flaw within a document to be sent to the customer. There will

be more than enough flaws that pass undetected without allowing the detected ones to

be sent out.

NOTE!

Widow words or clauses are those words or clauses that fall onto

the next page and are therefore separated from the bulk of the textthat causes them to make sense.

IMPORTANT!

An important point is that you own anything that is in your

document, even if you have cut and pasted from somewhere else. In

other words, make sure that you proof read everything, not just the

stuff that you have written.

REMEMBER!

Your document should be able to be read and understood by

anyone who can read and understand English. If most readers are

not able to understand what you have set out to say, you have failed

as a Technical Writer.

CAUTION!

Try to avoid having several informational prompts in a row such as

these four. In concentration they look untidy and they lose their

impact if too many are crowded together on the same page.


36/47

ATP Style Manual

Page 36

ABBREVIATIONS

We have mentioned abbreviations earlier with respect to apostrophes and with respect to

capitalisation. In this section we will look at other types of abbreviation. Commonly

accepted abbreviations include:

etc (etcetera)

eg (for example)

ie (that is)

Vs (versus)

The standard usage for etc, eg, and ie, are to place a comma before them and a full stop after.

The following examples illustrate the technique:

Today we will discuss the haultrucks gearbox, prop shaft and differential, etc.

There are several systems that constitute the haultruck, eg. Engine, transmission, chassis,

fuel system.

We will now discuss the haultrucks power plant, ie. the MTU V16 3000 series diesel.

NOTE

Normally these abbreviations would not appear at the beginning of

a sentence so there would never be any question of the first letter

of the abbreviation being capitalised.

WORKING DRAFTS

When we develop work off-site, the general rule is that the Technical Writer produces a

working draft on a word processor. This draft is then handed to the graphics team who

develop the necessary graphics and artwork. They then lay out the document in line with

ATP standards. The purpose of this is to ensure that the writing tasks are done as quickly as

possible and we achieve a consistent layout and appearance for all of our publications.

In the working draft, do the following:

indicate the need for headings and subheadings by placing an indicator of the require-

ment in brackets after the text (hdg, sh1, sh2, etc.)

indicate the need for a photograph in coloured text as follows as follows: Insert photo

V3 A21 Left-Hand Side of the Haultruck. This indicates which photograph and

indicates the caption you want. You can also explain any callouts that you may require.

indicate the need for graphics and cartoons with coloured text

insert any bullet points you require (all levels)

insert any numbered points that you require (all levels)

insert any tables that you require in the text

paginate the document so that it is easy to follow when it is printed.


37/47

ATP Style Manual

Page 37

In the working draft, do not do the following:

do not insert photographs, graphics and cartoons this makes the document too

difficult to manipulate on the slower computers

do not attempt to do the layout

do not add actual headings and subheads

do not insert headers and footers.

The short section below shows the standard way to present a given working draft to the

graphics and artwork department.

Equipment Introduction (sh 1)

The following sequence of photographs shows the main items of equipment that are used

in the deslimes and tails disposal circuit.

Insert diagram JA 1 of the Tails

Thickener System

The adjacent photograph shows the

tails thickener. The tails thickener

receives feeds from:

liquor addition

feed preparation thickener

overflow

cyanide bleed

new USX raffinate bleed

old USX raffinate bleed.

The underflow from the thickener is directed tothe surge tanks for disposal to the tailings dam. The

overflow is directed to the deslimes holding tank

where it will be forwarded to the deslimes cyclone

clusters.

The adjacent photograph shows the deslimes

holding tank. This tank receives liquid and solids

from the following locations:

underflow of CCD 6

overflow of the tails thickener

Photo ODV2Q35Tails Thickener

Photo ODV2Q31Deslimes Holding Tank


38/47

ATP Style Manual

Page 38

feed from liquor addition

bleeds from tails surge tanks A and B.

The materials are held in the tank and then pumped to the deslimes cyclone clusters

where the sands are separated from the slimes.

In the adjacent photograph, you can see

the agitator drive for the deslimes

holding tank. The tank is agitated to

ensure that the solids do not settle out

of solution at the bottom of the tank.

Deslimes Cyclones (sh2)

In the adjacent photograph you can see

the deslimes cyclone feed pumps.These pumps feed from the deslimes

holding tank directly into the cyclone

clusters. The delivery pressure is

controlled in line with metallurgists

instructions by switching on or off

individual cyclones as required.

Photo ODV2Q35Agitator Drive

Photo ODV2Q35

Cyclone Feed Pumps


39/47

ATP Style Manual

Page 39

In the adjacent photograph, you can see

the two deslimes cyclone clusters. Each

cluster contains 12 individual cyclones.

The cyclones are used to separate the

useful sands from the waste slimes. The

sands are heavier than the slimes and

are, therefore, directed to the

underflow of the cyclone. From the

underflow they are sent to the sands

handling circuit from where they will be

sent to the CAF plant. The cut-point

and, therefore the manifold pressures,

are determined by metallurgists.

The adjacent photograph shows the coarse sands

holding tank. The coarse sands which are collected

from the underflow of the cyclones are held in this

tank until the personnel at the CAF plant are ready

to receive a new batch. Once a batch has been

sent to the CAF plant, the lines are flushed with

mine process water to ensure that pumps and the

lines are kept clear for the next batch of sands.

Cartoon 27 Cartoon of a guy at the CAF plant

mixing sands with concrete to make a fill for the U/

G mine

Photo ODV2Q31Coarse Sands Holding Tank

Photo ODV2Q35Cyclone Clusters


40/47

ATP Style Manual

Page 40

SUMMARY

The above sections have outlined some of the basics of the ATP style standards. In some

cases the style manual only offers guidelines Technical Writers are expected to write to

suit current requirements. The important thing is for our presentation to be consistent

throughout any given document and we must be consistent across a range of documents for

a given customer.

We should also be concerned to try to eliminate the most common errors from the material

that we develop. Passive voice sentences, sentence fragments, spelling errors, bad grammar

and syntax and poor use of punctuation and style, all work to make our documentation look

something less than professional.

As mentioned several times in the above text, the quality and appearance of our

documentation is what sets us apart from the opposition and what will help us to obtain

repeat work from any given customer. Achieve consistent, high standards and we will allmaintain secure jobs that provide a reasonable income.


41/47

ATP Style Manual

Page 41

TOPIC TWO QUALITYBASICS

INTRODUCTION

The previous section has covered the basics of Technical Writing styles. This section looks at

our methods of achieving consistent quality. To be consistent, you need to know what

constitutes the norm. In ATPs case, the norm is a training package. Most other

documentation is a derivative of the training package. The following section outlines what iscontained in the standard ATP training package.

WHATISA STANDARD ATP TRAINING

PACKAGE?

A standard ATP training program contains the following:

Custom designed cover and spine This is designed specifically for the customer

by the ATP Graphics Department.

Laminated table of contents This lists the topics that are covered in the training

program.

Informational Prompts PagePage detailing the informational prompts that are

used throughout the manual.

Module DescriptorThis follows a well-established format which contains adminis-

trative information about the training program.

Lesson Plan Summaries These outline the main points for the trainer. They are

designed for the trainer who has delivered this training program a number of times and

who only requires a reminder of the main points.

Detailed Lesson PlansThese are designed for the trainer who is going to deliver

the training program for the first or second time. They are designed to cover all the

points that the trainer should cover in the course of delivery. As well as detailing the

points that should be covered, they also give the trainer information about when to use

OHTs and other training aids.

Topic Table of Contents This list the headings that are used throughout the given

topic.


42/47

ATP Style Manual

Page 42

Trainees Text This is the same text that will be handed to the trainees during their

training. This contains full colour pages (with photographs, graphics, cartoons, etc) that

provides all the information that the trainee needs to be able to become competent in

the given discipline.

Theory AssessmentTheory assessments are use to determine competence in areas

where it is impossible to conduct practical assessment. Typically this includes suchissues as PPE, hazards, tagging, pipe markings, etc. The theory assessment is normally in

multi-choice

Practical AssessmentPractical assessments are the favoured method to test a

persons competence in a given task or discipline. The current ATP practical assessment

template consists of a number of columns which


43/47

ATP Style Manual

Page 43

THE DEVELOPMENTPROCESS

It is almost impossible to prescribe a definite process for the development of a training

manual or a technical document. The best we can do is work to a basic agenda which is

outlined in this section. Remember, there will be variations in the development process

dependent on client needs and the requirements of the project. Where the process flow

does not work, the Technical Writer should be able to improvise and work through the

project in a logical manner.

The general development process is as follows:


44/47


45/47

ATP Style Manual

Page 45

11. The writer of the review copy conducts his/her own proof-reading before it is dis-

patched to the client. One other writer may be asked to proof-read the document if

deemed necessary. Normally, second/third-person proof-reads are not a viable option

due to the need to minimise costs.

12. At the completion of development and in-house proof-reading, the agreed number of

review copies (and/or electronic copies as agreed) are sent to the nominated sitecontact or review person. At this time, an invoice is included with the documentation

that has been dispatched. This is one of the main reasons why the review copy of the

documentation should be as close as possible to a final product. In many cases, review

and amendment will not take place due to pressures of work at the clients site. In

these cases we expect that the document will serve its intended purpose with no

further input from either the client or ATP.

13. Normally, once the document/s have been reviewed on site, the reviewed copy is

returned to ATP. The client should annotate relevant pages of the document with

meaningful comments. In the scoping stages of the project, it is important to ensure

that the client knows that the review must be meaningful there is no value incomments such as: we dont do it like that or this is wrong or is this correct?. These

comments are next to useless when trying to review a manual.

14. ATP incorporates all appropriate amendments arising from the review. If review

comments seem incorrect or inappropriate, we should carefully check to make sure

that what we are about to include in the documentation makes sense.

15. The agreed number of final hard and electronic copies of the documentation are then

supplied to the client.

16. ATP creates one hard copy and two electronic copies on CD. One of the CDs is

stored at the ATP office for future reference and the second copy of the CD is stored

off-site to provide fail-safe archiving.

17. ATP continues to offer a review and continual improvement for any document it

develops. These services are charged out at the prevailing rate.

REMEMBER!

The above outline does not constitute a hard and fast methodology

which should always be painstakingly followed. Obviously prevailing

circumstances will cause the flow of documentation development to

vary from project-to-project.


46/47

ATP Style Manual

Page 46

SUGGESTED FURTHER READING

All of the publications mentioned below are available in the ATP office.

Communicating or Just Making Pretty Shapes by Colin Wheildon.

Editing for Print Geoffrey Rogers

Fowlers Modern English Usage by HR Fowler

Handbook of Practical English by RC Cornish

The Little, Brown Handbook by HR Fowler; JE Aaron and D Anderson

The Professional Writing GuideWriting well and Knowing Whyby Roslyn Petelin andMarsha Durham

The Shorter Oxford English Dictionary

Queensland Government Style Guide

Australian Government Style Guide

Rogets Thesaurus.


47/47

ATP Style Manual

VISION/MISSION STATEMENTS

VVVVVISIONISIONISIONISIONISION SSSSSTATEMENTTATEMENTTATEMENTTATEMENTTATEMENT

Our vision is to build a company that is universally respected within

industry as reliably and consistently producing the best technical

documentation available within a reasonable price structure.

MMMMMISSIONISSIONISSIONISSIONISSION SSSSSTATEMENTTATEMENTTATEMENTTATEMENTTATEMENT

Our mission is to research, develop and produce world class

technical documentation for industry in both the domestic and

international markets which assists in enhancing efficiency and in

improving safety awareness.

Documents

ATP Style Manual 01