A how-to manual on technical report writing - why the art of Chocolate Cake ?
I was asked to "throw " a presentation together with minimal time to prepare - tech report writing could be a very dry subject - but then I decided to compare it with baking a chocolate cake - either very simple or extremely complex
The key issue is to deliver what the consumer wants - a relevant report or a delicious chocolate cake.
Mysore Call Girls 8617370543 WhatsApp Number 24x7 Best Services
Technical Report Writing - Chocolate Cake K Christian
1. A Technical Report Writing
Manual
& The Art of Chocolate Cake
Kerrie Anne Christian 2009
1
2. In Summary :Technical Report Writing & The Art of
Chocolate Cake
What are the key aspects of Technical Report Writing ?
1.
Like baking chocolate cakes – there are different types of Technical
2.
Reports
Technical Report Writing is a Communication process
3.
Focus on your Reader – just as people prefer different types of
4.
Chocolate Cake
Clearer Writing - Goldilocks & Gunning Fog Index
5.
Plan your work – just like organising before making Chocolate Cake
6.
Remember - cooks swap Chocolate Cake recipes & hints
7.
After you have drafted the report – let it sit – then check it
8.
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
11.
Prince
Hints – Dealing with Writer’s Block
12.
Practice & don’t forget to enjoy Chocolate Cake
13.
2
3. Navigating the Information Maze
ERP :
Other Event
Event
SAP
system PC’s,
Capture Steel Direct
System - A Emails
Intranet OHS system
Networks
Doc Management alternate
Communities System
of Practice
Mainframe
OHS System
Sharepoint
Servers - main
Engineering
Records Books, articles,
manuals,
Contractor’s procedures, trade
Dept Hard
Network info, newsletters
Wiki’s Dept
copy records
Reports
files
Library Site & Depts
Standard Procedures 3
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 quot;necessary evilquot;, 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. 4
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)
5
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
6
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
7
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
8
– very different approach – lots of how to photos, comprehensive
9. Writing : Clarity, Simplicity, Concise … what about
Factual?
Question : Do we all see the world the same way : or do we filter
facts based on our personal experience, bias & priorities ?
Knowledge in the Message containing Knowledge in the
mind of person A information mind of person B
Seek feedback to
Seek feedback to
check ififyour
check your
message has
message has
gotten through
gotten through
9
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?
10
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 understand
This is too short. It’s too childish
This is just right for me, as I can
understand it easily.
So how can we work out how hard our
writing is to read ?
11
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)
•
12
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?
13
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
Medium Tech
Blinky Bill 8 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 25 Cadet 10 19
Long complex novel
NB. Media articles sometimes have one-sentence paragraphs & surround with lots of white space 14
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
15
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
16
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
17
18. Avoid ….
Avoid wasted words – use adjectives only when it
contributes to the writing
But beware excess brevity
You may miss out key information
Your 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
18
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 ?
19
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
20
21. Clearer Words – Suggest Alternative Words for ….
Endeavour
Detrimental
Verification
Simultaneously
Concur
Sufficient
Ascertain
Modification
Deferral
Consequently
Accelerate
Possess
Anticipate
Capability
Configuration
Numerous
Remuneration
Punctual
Align with your local “work culture” & its terminology.
What words or jargon are part of your local “work culture”?
Do outsiders understand them ? 21
22. Plan Your Work
Consider 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! 22
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 it
later)
Introduction or Background - What was the work done for ?
Body
Conclusions - What were the findings ?
23
Recommendations – Action Items
24. Structure of a Report :
Introduction, Discussion, Conclusion
Introduction : Should attract reader’s interest
I have an all-consuming interest in beer.
Discussion : Substantiate findings – write clearly & forcefully
I 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?
24
25. Plan Your Work First :
How will you sequence your report?
Different Approaches
Chronological or Time Order
Spatial or Geographic Order
Well known to less known
Order of Importance
Eg How would you sequence the following ?
Recipe – eg Chocolate Cake
Description of the Steelworks
Instructions on how to use a Fire Extinguisher
Report on One Day Cricket Match
25
Description 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 !
26
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 27
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
template
You may need more than one report type – for
different styles
Save 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 block
If 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 ? 28
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
engineering
offers 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
29
30. More Practical Hints
Gather & keep resource material on hand
relevant to your technical area – don’t overdo it
Eg 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 & problems
Remember your network may have other information which will help you
Writing is a communication process –people may think differently
Don’t ignore past data because you didn’t generate it, or it’s not electronic
Make sure you have weighed up all the evidence, not just what suits your
view
Would KT, RCA, FMEA or Five Why’s help to make sure everything’s
covered ?
If results look wrong – check them out – just in case
Be 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 !
30
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 report
reference 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
31
32. The “Nuts & Bolts” of Technical Reports
Date & Reference Number
To (Reader) & From (Writer) - also Authorisation, Distribution List
Subject or Title
Introduction - sets context & purpose – VIP – sometimes skimped on
Complete, concise statement of problem & its importance
May include brief overview of problem’s history & current status
Should attract reader’s interest
Data - text, tables, graphs, sketches, photos, calculations
May be included in the main body or an appendix
Organise logically – not “all over the place”
Be accurate
Discussion
Helps to start with main finding – unlike school essays & fairly tales
Organise findings logically – developing aims stated in Introduction
Substantiate findings – write clearly & forcefully
Be accurate
Conclusions & Recommendations – ties together the whole report
Should give an impression of completeness & of positive gain
However 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 & poorly
constructed
32
33. Techniques
Headings
Announce Key Points
Allows readers to choose key points they are
interested in
Stop points – convenient place for readers to
stop & assemble their thoughts
Make sure heading is not on bottom of page & its
text on next page
White Space
A report that is visually pleasant is easier to read
& gains easier acceptance
Use plenty of space between paragraphs, around
headings, figures, tables & borders
33
Makes the report more attractive & easier to read
34. Techniques
Paragraphs
Not too long - large ones become a strain on the eye & mind
Average about 7 – 8 lines
For emphasis, one line can be a paragraph
Consider whether to number each paragraph & point
Use 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 format
Consider whether you should save as Word or PDF format
Organise your report notes – plastic sleeve, ring binder, electronic files 34
Are there local area requirements for writing reports – standard procedures
35. Photos, graphs & charts can communicate a lot
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 !
35
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?
36
37. The Art of Persuasive Writing
– with apologies to Machiavelli’s “The Prince”
Be accurate & clarify that they have received & understand the bad news
Be respectful of others – be aware of strong views / bias of your readers
If your findings are controversial – identify potential supporters & detractors
Try 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
direction
Make 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 inappropriate
If your recommendation means a change that affects performance negatively
– be diplomatic
Don’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 processes
Technical reports should not be emotive nor an ego exercise 37
38. More Practical Hints
– Also Helpful in Bad News Situations
Gather & keep relevant resource material on hand – don’t overdo it
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 & problems
Remember your network may have other information which will help you
Writing is a communication process – remember people may think differently
Don’t ignore past data because you didn’t generate it, or it’s not electronic
Make sure you have weighed up all the evidence, not just what suits your
view
Would KT, RCA, FMEA or Five Why’s approaches help, to make sure
everything’s covered ?
If results look wrong – check them out – just in case
Ask dumb questions to clarify your understanding if necessary
Remember you are part of a team – get help if you need it
you are not flying totally solo ! 38
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 39
40. In Summary :Technical Report Writing & The Art of
Chocolate Cake
What are the key aspects of Technical Report Writing ?
1.
Like baking chocolate cakes – there are different types of Technical
2.
Reports
Technical Report Writing is a Communication process
3.
Focus on your Reader – just as people prefer different types of
4.
Chocolate Cake
Clearer Writing - Goldilocks & Gunning Fog Index
5.
Remember cooks swap Chocolate Cake recipes & hints
6.
After you have drafted the report – let it sit – then check it
7.
The “Nuts & Bolts” of Technical Report Writing – don’t forget the visuals !
8.
What if you have to deliver bad news ?
9.
The Art of Persuasive Writing – With Apologies to Machiavelli’s The
10.
Prince
Hints – Dealing with Writer’s Block
11.
Practice & don’t forget to enjoy Chocolate Cake
12.
40