1

& The Art of Chocolate Cake

Kerrie Anne Christian 2009

A Technical Report Writing Manual

2

In Summary :Technical Report Writing & The Art of Chocolate Cake

1. What are the key aspects of Technical Report Writing ?2. Like baking chocolate cakes – there are different types of Technical

Reports3. Technical Report Writing is a Communication process4. Focus on your Reader – just as people prefer different types of

Chocolate Cake5. Clearer Writing - Goldilocks & Gunning Fog Index6. Plan your work – just like organising before making Chocolate Cake7. Remember - cooks swap Chocolate Cake recipes & hints8. After you have drafted the report – let it sit – then check it9. The “Nuts & Bolts” of Technical Report Writing – don’t forget the visuals !10. What if you have to deliver bad news ?11. The Art of Persuasive Writing – With Apologies to Machiavelli’s The

Prince12. Hints – Dealing with Writer’s Block 13. Practice & don’t forget to enjoy Chocolate Cake

3

Navigating the Information MazeEvent

Capture System - A

Other Event system

ERP : SAP Steel Direct

Site & Depts Standard Procedures

Communities of Practice

Engineering Records

Sharepoint

Intranet

OHS System - main

Doc Management System

Contractor’s Network

Networks

Servers

Dept Hard copy records files

Wiki’s

Library

Dept Reports

PC’s, Emails

Books, articles, manuals, procedures, trade info, newsletters

Mainframe

OHS system alternate

4

Technical Report Writing – course participants said

needs to be concise to clearly communicate an engineering problem and solution.

the most useful application of the English language. It is where the creativity of the form of language is harnessed by the logic of engineering thought.

an underappreciated and underused skill - documentation often appears to be treated as a "necessary evil", and many people do not give it the attention it deserves.

a quick and easy method of communicating a scientific or complex idea.

a method of conveying information in a clear and concise manner, so that it can be easily understood by a variety of audiences

a vital skill for all engineers as it is the most effective way to communicate complex ideas to a variety of audiences.

5

Technical Report Writing – they said …The University Science Professor said ….

be concise, precise & clear(writing is hard work)

The Engineering Manager said ….

remember the KISS Principle – Keep It Simple Stupid( & keep paragraphs short)

CEO said …. is valuable – I learnt to do it when I was in the Technology area be factual (my wife’s postcards are probably more interesting – but mine do get

the facts down)

6

Technical Report Writing –other course participants said

• an important skill as it is one of the most effective methods for engineers to communicate ideas to interested parties

• a writing style to express technical aspects of something one has investigated.

• important tool for transferring information and ideas, but it can often be difficult to do this in a clear and concise way

• should be written in a way that communicates the subject matter clearly and concisely

7

In Summary : Technical Report Writing– key aspects?Communicate

Style - Concise & Clear

Simple & Effective

Investigation

Subject Matter - Factual ( rather than having to be interesting )

Logical & Creative

Complex ideas

May have variety of Audiences

Skill - requires Practice

Tool

8

Writing Reports & Cooking Chocolate Cake

All include ingredients, equipment, time, temperature, size …

Commonsense Cookbook – brief, assumed knowledge & experience, no photos

AWW Cookbooks – for the non expert, lots of photos, simple steps & ingredients

Donna Hay / Jamie Oliver – “simple made special” – good photo, simple steps

A Gourmet Traveller – lots of steps, unusual ingredients, time consuming, way over the top, carried away with the process -almost forgets the goal of eating yummy chocolate cake

Taste.com.au – web based – good photo, easy steps, normal ingredients

Cookingforengineers.com – web based – very different approach – lots of how to photos, comprehensive

9

Writing : Clarity, Simplicity, Concise … what about Factual?

Knowledge in the mind of person A

Message containing information

Knowledge in the mind of person B

Question : Do we all see the world the same way : or do we filter facts based on our personal experience, bias & priorities ?

Seek feedback to check if your message has gotten through

Seek feedback to check if your message has gotten through

10

Writing : It’s not just about you – It’s about the reader!

Ask yourself a few questions …

What am I trying to achieve with my writing? : Today, next week, next

year, 10 –20 years

Who are my readers ? Do they want a brief or comprehensive report ?

How familiar are they with my subject?

How familiar are they with my technical jargon & concepts?

Are they receptive to my work?

How busy are they?

How will my report be read? : Hard copy or computer screen

Will it be stored? Where?

11

Complexity : Goldilocks & the Gunning Fog Index

This is too hard too read, and it has too many long sentences, with too many hard

long words, that I don’t understandThis is too short. It’s too childishThis is just right for me, as I can

understand it easily.

So how can we work out how hard our writing is to read ?

12

Complexity : Goldilocks & the Gunning Fog Index

Read a paragraph from the material in front of you

How easy was it to read : too hard / too childish / just right ?

Select one paragraph • what is the average no. of words per sentence = A (eg 162/6

= 27)

• what is the % of words with >2 syllables in the paragraph = B (eg 18/162 = 11%)

• Calculate C = A + B (eg 27 +11 = 38)

• Calculate GF Index = C x 0.4 (eg 38 x 0.4 = 15.2)

What does this mean?

13

Clarity Measures – Gunning Fog Index aka Years of Education needed for adults reader to understand a written article

Writing Level Gunning Fog Index (GFI) Education Level

Childish 6 – 8 Primary School

Acceptable (simple) 8 – 10 Junior High School

Ideal 10 – 12 Senior High School/TAFE

Acceptable (difficult) 12 – 14 Uni Undergraduate

Difficult 14 –1 7 Uni Graduate

Unacceptable 17 + (Sir Humphrey)

Now repeat with your own writing – what does it tell you about this piece of your own writing?

14

Clarity Measures – Gunning Fog Index aka Years of Education needed for adults reader to understand a written article

Item GFI Item GFI Item GFI

Goosebumps 7 IM Soccer 15 Cadet 1 11

Blinky Bill 8Medium Tech

Article 16 Cadet 2 12

The Hobbit 9 SMH Editorial 17 Cadet 3 13

Harry Potter 10 Lord of the Rings 17 Cadet 4 13

Girlfriend Mag 11 The Bulletin Mag 18 Cadet 5 13

SMH Political Article 11 IM Soccer 18 Cadet 6 15

Light Tech Article 12 IM Rugby League 18 Cadet 7 15

Lonely Planet Guidebook 13 New Scientist 21 Cadet 8 15

Australian Geographic 14 Heavy Tech Article 25 Cadet 9 18

SMH Political Article 14 Long complex novel 25 Cadet 10 19NB. Media articles sometimes have one-sentence paragraphs & surround with lots of white space

15

Clearer Writing : A Few General Comments

Use clear, familiar words

Keep most sentences short & simple : 1 basic idea & 15-25 words

Use active verbs not passive : I wrote the report

Personalise your writing where possible – but generally avoid in technical reports

Use a conversational style (not slang) where possible – but not in technical

reports

The harder the ideas – the greater the need for clarity - so as to be understood

One main idea or theme per paragraph – use connecting words between

sentences

Gather all the information you need before you start writing – like the chocolate

cake

16

Which sounds best - for a clear & concise technical report?

I don’t have a clue

I wouldn’t have the foggiest

Stuffed if I know

It is an enigma

It is not clear

I don’t know

The causal factors that were at play were unknown

17

Simpler Sentences

Keep it to a single idea, or risk that one of the ideas may be “buried”

15 – 25 words long

Active not passive – balance this with conciseness

Put the main idea at the front of the sentence

If you have long sentences, try chopping them up – “Meat Cleaver” them

Then use connecting words to make the sentences flow

18

Avoid ….

Avoid wasted words – use adjectives only when it contributes to the writing

But beware excess brevity You may miss out key informationYour writing may appear too abrupt or overbearing

Avoid adjectives such as unique, exceptional, marvellous

Generally avoid colloquialisms, foreign phrases, tautology

Colloquial okay for blogs etc

19

Active vs Passive

Nathan bounced the ball. (Active)

The ball was bounced. (Passive)

The ball was bounced by Nathan. (Passive)

Which is easier to understand ?

20

Examples. What is the main point? Which is clearer?

•Given all the operating factors involved, the long lead time for delivery, the tight constraint on labour availability, it was therefore decided to defer the project for six months, although this would be at the risk of increasing equipment unreliability and safety concerns which would have to be identified and managed in a timely fashion.

•Management decided to defer the project for six months because of a range of concerns. These included operating factors, long delivery lead times and tight labour resources. However they recognised need to to identify the risks of increasing equipment unreliability and safety concerns. They would then need to ensure that these were managed with the right priority.

•Management Decision : Project Deferred 6 months•Constraints - Operating factors, long delivery lead times, tight labour availability•Potential Consequent Risks – Increased equipment unreliability, safety concerns

• Need to identify, prioritise & manage

21

Clearer Words – Suggest Alternative Words for ….

DetrimentalSimultaneouslySufficientModificationConsequentlyPossessCapabilityNumerousPunctual

EndeavourVerificationConcurAscertainDeferralAccelerateAnticipateConfigurationRemuneration

Align with your local “work culture” & its terminology.

What words or jargon are part of your local “work culture”? Do outsiders understand them ?

22

Plan Your WorkConsider the report’s Purpose : What was the work done for ?

The Content : Should answer

Who

What

When

Where

How

Why

Don’t forget your readers!

23

Plan Your Work – Develop an Outline First

Jot down points – then organise your points

Executive Summary - One Page – Absolutely important for reports >3 pages

( Experts say - appears first – but should be done last)

(Kerrie says – if you know your topic you could start it ,first then review itlater)

Introduction or Background - What was the work done for ?

Body

Conclusions - What were the findings ?

Recommendations – Action Items

24

Structure of a Report : Introduction, Discussion, Conclusion

Introduction : Should attract reader’s interestI have an all-consuming interest in beer.

Discussion : Substantiate findings – write clearly & forcefullyI feel the perfect schooner glass of ones favourite amber liquid can be one of the most rewarding and satisfying experiences of ones time. If prepared at the perfect temperature of both glass and contents, poured with skilled hands from a quality tap, served at a time of completed challenges on a warm afternoon, in an atmospheric yet relaxed establishment, while amongst close friends, then the perfect beer will result, and this is what my interest is all about.

Conclusion: ties together the whole report -> completeness Some may cynically say this is only a chemical interest, and that I am merely addicted to the drug, and others may even call me an alcoholic. Perhaps I am, but I am happy, and isn’t that what really matters?

25

Plan Your Work First : How will you sequence your report?

Different ApproachesChronological or Time OrderSpatial or Geographic OrderWell known to less knownOrder of Importance

Eg How would you sequence the following ?Recipe – eg Chocolate Cake

Description of the SteelworksInstructions on how to use a Fire ExtinguisherReport on One Day Cricket MatchDescription of your Department

26

Like the Chocolate Cake – Gather all your information before you start to write …

You cannot write an idea clearly until you have thought it out clearly.

You cannot think an idea out clearly until you have all the information.

(Why? If you have all the information, you should be more confident that you know your subject.

If you are more confident, then your writing style will be clearer.)

Note : with PC word processing, it may be possible to relax the above rule – but not throw it out !

27

Hints : Dealing with Writer’s Block

Good idea to start with a layout with section headings

Start writing the section that you find easiest

If it is hard to make a start, just start writing

Don’t worry about grammar or punctuation at this stage

If it is still hard – imagine you are telling someone about the problem – why you did the work, what you found & what you recommended

Then write it down (or type) as if you were talking to them about it

Just get it down – you can fix it up later

28

Remember Cooks swap recipes & hints for Chocolate Cake !

Identify someone who writes well in your area Get copies of their reports Use a copy of a well written report as a templateYou may need more than one report type – for different stylesSave them on Word If you find a good sentence somewhere else –save it in a “Useful File”Use them – especially if you have writer’s blockIf a previous report has been written on the topic - get a copy Read the previous report & look at the writing style – can the style be improved ?

29

Remember Cooks swap recipes & hints for Chocolate Cake !

Identify a report writing advisor or mentor –someone who

writes well has time & is willing to review your writing is familiar & has expertise with your area & field of engineeringoffers positive, constructive advice – not just identifying the negatives

Respect your advisor & their suggestions, even if you do not agree with everything

Thank them for their time taken to help you – they are busy people

30

More Practical HintsGather & keep resource material on hand

relevant to your technical area – don’t overdo itEg hard copy articles, handbooks, electronic, web sites

Avoid re-inventing the wheel – it’s okay to get help from others Develop a network to bounce around ideas & problemsRemember your network may have other information which will help youWriting is a communication process –people may think differentlyDon’t ignore past data because you didn’t generate it, or it’s not electronicMake sure you have weighed up all the evidence, not just what suits your viewWould KT, RCA, FMEA or Five Why’s help to make sure everything’s covered ?If results look wrong – check them out – just in caseBe prepared to ask dumb questions to clarify your understanding Remember you are part of a team – get help if you need it

you are not flying totally solo !

31

After you have gotten a draft together - remember

Let it sit after you have written a draft

Check what you have written

Have I identified in the introduction - the area of plant, type or equipment or product, identification or serial nos., past reportreference numbers

Alter if necessary - order of words, sentences, paragraphs, whole sections

Reject obscure, long-winded or inappropriate words & phrases

When you use jargon or technical terms, explain them

Proof read carefully - Spell check

Don’t forget punctuation – commas, full stops, apostrophes etc

Does it actually say what you thought it was supposed to say ?

Is it logical ? – but don’t ignore hunches – nor be blinded by them

32

The “Nuts & Bolts” of Technical ReportsDate & Reference NumberTo (Reader) & From (Writer) - also Authorisation, Distribution ListSubject or TitleIntroduction - sets context & purpose – VIP – sometimes skimped on

Complete, concise statement of problem & its importance May include brief overview of problem’s history & current statusShould attract reader’s interest

Data - text, tables, graphs, sketches, photos, calculationsMay be included in the main body or an appendixOrganise logically – not “all over the place”Be accurate

DiscussionHelps to start with main finding – unlike school essays & fairly talesOrganise findings logically – developing aims stated in IntroductionSubstantiate findings – write clearly & forcefullyBe accurate

Conclusions & Recommendations – ties together the whole reportShould give an impression of completeness & of positive gainHowever may pose unanswered questions for future work

References (aka Bibliography)Not as rigorous as a uni report – but still courteous to acknowledge others’work

Appendix Used where including the data would make the body large & poorlyconstructed

33

TechniquesHeadings

Announce Key PointsAllows readers to choose key points they are interested inStop points – convenient place for readers to stop & assemble their thoughtsMake sure heading is not on bottom of page & its text on next page

White SpaceA report that is visually pleasant is easier to read & gains easier acceptanceUse plenty of space between paragraphs, around headings, figures, tables & borders Makes the report more attractive & easier to read

34

TechniquesParagraphs

Not too long - large ones become a strain on the eye & mindAverage about 7 – 8 linesFor emphasis, one line can be a paragraphConsider whether to number each paragraph & pointUse dot points to help draw the eye down the page & break up a paragraph

Underline, Bold or Italics for Emphasis Don’t overdo it or the effect will be lost

Don’t forget Margins & Page Numbering

Word vs PDF formatConsider whether you should save as Word or PDF format

Organise your report notes – plastic sleeve, ring binder, electronic filesAre there local area requirements for writing reports – standard procedures

35

save a lot of words – but don’t use too few or too many

if lots – put them in an appendix or attachment at the back

clear, in focus– use white space around the photos

don’t cram too many too close together

use captions or annotations & arrows where appropriate

don’t make the reader guess !

Photos, graphs & charts can communicate a lot

36

What if you have to deliver bad news ?

Management is under pressure to deliver on performance, time, budget & safety

Your report may tell them that they are not going to achieve their kpi’s

equipment won’t last until the next annual (scheduled) shutdown

can’t achieve required product properties or budgeted tonnages

budget is blown by maintenance spares costs blowing out

What do you do?

37

The Art of Persuasive Writing – with apologies to Machiavelli’s “The Prince”

Be accurate & clarify that they have received & understand the bad newsBe respectful of others – be aware of strong views / bias of your readersIf your findings are controversial – identify potential supporters & detractorsTry to avoid a clash with your supervisor or customer & don’t back people into corners Diplomatically state the past bad practice as a result of constraints, then move on to to the need for future improvement & acknowledge improvements in that directionMake story fit the facts & not facts suit the story - avoid selective use of facts Be ethical – don’t alter to suit someone’s agenda if inappropriateIf your recommendation means a change that affects performance negatively – be diplomaticDon’t hide bad news for fear of retribution – identify risks & be diplomatic

Careful Connectors eg unfortunately.., fortunately…, it would appear that…, on weighing up the situation …, consideration should be given to …., a review of all factors has shown…

Consider confidentiality & legal /privilege issues – Discovery processesTechnical reports should not be emotive nor an ego exercise

38

More Practical Hints – Also Helpful in Bad News Situations

Gather & keep relevant resource material on hand – don’t overdo ithard copy articles, handbooks, electronic, web sites

Avoid re-inventing the wheel – it’s okay to get help from others Develop a network to bounce around ideas & problemsRemember your network may have other information which will help youWriting is a communication process – remember people may think differentlyDon’t ignore past data because you didn’t generate it, or it’s not electronicMake sure you have weighed up all the evidence, not just what suits your viewWould KT, RCA, FMEA or Five Why’s approaches help, to make sure everything’s covered ?If results look wrong – check them out – just in caseAsk dumb questions to clarify your understanding if necessaryRemember you are part of a team – get help if you need it

you are not flying totally solo !

39

Hints : Dealing with Writer’s Block

Good idea to start with a layout with section headings

Start writing the section that you find easiest

If it is hard to make a start, just start writing

Don’t worry about grammar or punctuation at this stage

If it is still hard – either imagine, or actually, talk through the problem with someone – why you did the work, what you found & what you recommended

Then write it down (or type) as if you were talking to them about it

Just get it down – you can fix it up later

40

In Summary :Technical Report Writing & The Art of Chocolate Cake

1. What are the key aspects of Technical Report Writing ?2. Like baking chocolate cakes – there are different types of Technical

Reports3. Technical Report Writing is a Communication process4. Focus on your Reader – just as people prefer different types of

Chocolate Cake5. Clearer Writing - Goldilocks & Gunning Fog Index6. Remember cooks swap Chocolate Cake recipes & hints7. After you have drafted the report – let it sit – then check it8. The “Nuts & Bolts” of Technical Report Writing – don’t forget the visuals !9. What if you have to deliver bad news ?10. The Art of Persuasive Writing – With Apologies to Machiavelli’s The

Prince11. Hints – Dealing with Writer’s Block 12. Practice & don’t forget to enjoy Chocolate Cake