Technical Writing skills

April 2020
VALUE MOMENT

2
 Training objectives

By the end of this session, you would

▪ Enhance your understanding of the essential Report

Writing skills

▪ Gain practical tips on report writing

3
 The purpose and significance

We call ourselves a leading EPCI organization. Effective

report writing should be our forte because:

Reports showcase the work that we as engineers

perform.

Report writing is an integral part of our work.

It is a reflection of our company’s capabilities,

knowledge base and reputation.

4
 Ground rules

Actively participate

Share experiences

Ask relevant questions

Give our hand phones a break

5
 What is technical writing

Technical writing is a type of writing where the author is writing about a

particular subject that requires direction, instruction, or explanation. This style of
writing has a very different purpose and different characteristics than other
writing styles such as creative writing, academic writing or business writing.

The subject of technical writing can either be:

Tangible - Something that can be seen or touched, such as a computer or
software program, or information on how to assemble a piece of furniture.
Abstract - Something that involved a series of steps that aren't related to a
tangible object. One example of this might be steps required to complete an
office process.

6
 What is technical writing

Regardless of the type of document which is written, technical writing

requires the writer to follow the properties of knowing their audience,
writing in a clear, non-personal style and doing extensive research on
the topic. By including these properties, the writer can create clear
instructions and explanations for the reader.
Know your audience. An expert in the field will understand certain
abbreviations, acronyms, and lingo that directly applies to such a
field. The novice will not understand in the same manner and,
therefore, every detail must be explained and spelled out for them.
Use an impersonal style. Write from a third person perspective, like a
teacher instructing a student. Any opinions should be omitted.

7
 What is technical writing

The writing should be straightforward, to the point, and as simple as

possible to make sure the reader understands the process or
instruction. This at times may appear as simply a list of steps to take
to achieve the desired goal or may be a short or lengthy explanation of
a concept or abstract idea.
Know how to research. Gather information from a number of sources,
understand the information gathered so that it can be analyzed
thoroughly, and then put the information into an easy to understand
format to instruct those who read it. The more inexperienced your
audience, the more information you will need to gather and explain.
Be thorough in description and provide enough detail to make your
points; but, you also have to consider that you need to use an
economy of words so that you do not bore your reader with gratuitous
details.

8
 Communication barrier

• ENCODED • DECODED
MESSAGE MESSAGE

Communication
Communication

NOISE NOISE

medium
medium

NOISE NOISE

• SENDER • RECEIVER

Feedback/ Perceptual, semantic and

cultural barriers are examples
Acknowledgemen of noise that can interfere with
t written communication.

9
 Semantic barrier

The word semantics has its origin in Greek and is taken from the word
semantikos, which means showing signs or symptomatic.

Semantic barriers come from differences in language, education, and

culture.

The same words and symbols have different meanings to different people.
▪ The meaning intended by the sender may be dissimilar from the meaning followed by the
receiver.

▪ People understand the message in terms of their own behavior and

experience

10
 Other barriers

One way communication.

No opportunity to explain additional details to the

audience.

No control over the actual audience.

No recalls – once signed and issued.

It may not be entirely read (selective reading).

11
 Well written reports
Are organized.

Are consistent in language, grammar, numbers, units and presentation.

Convey knowledge and depth of experience of the author.

Are an indication of professional standing of the author.

Are a critical tool for decision making and documentation.

Show that we take pride in our work.

Presenting the report to target audience in a structured, clear and easily understandable
manner is part of an engineer’s work.

12
 The intent of reports

Sharing the thought process/ rationale with all relevant stakeholders.

To prove that necessary standards, contractual and statutory obligations

are adhered to.

To substantiate and document decision making.

To serve as a basis for future reference.

13
 The preparation
• What is the scope of the report?
• Who will be the audience for the report?
• What should be the key takeaways of this report?
ASK • Who can I go to for gathering the content for this report?

• Gather all the relevant material together from all data sources
• Create a mind map or logical progression of what the report should be
DO • Create a table of contents as your roadmap for the report

• You have knowledge of the McDermott report writing examples

• You have access to all tools and background information needed
ENSURE • You stick to the relevant and not use it to dump all that you know

14
 The writing
Make it clear, crisp, simple and interesting

Remember WR3

Write it
Review it
Revise it
Re-read it

Put yourself in the recipient’s position and see if it

conveys what you want to say
15
 The language
Language should be simple, yet professional
Rhetoric is important

Tips
Reports should be written in third person.
Break-up long sentences for clarity.
Pay attention to consistency of tone.
Use ‘conducted’ or ‘performed’ or ‘carried out’ instead
of ‘done’
Use ‘informed’ or ‘advised’ instead of ‘told’

16
 Guidelines for sectioning
Cover sheet

Executive Summary (where needed)

Revision history

Table of Contents

HOLDS List (if applicable)

Introduction, Background and Purpose

Abbreviations (this is a must) and Glossary

Body of the report

Key Results

Analysis

Conclusions

References

Appendices

Use the above, but adapt to report requirements

17
 Executive summary
When and where to present an Executive Summary?

When content is read by various levels and across functions , example

▪ Senior and functional management
▪ Design engineers
▪ Operations

When the result of any technical investigation is to be presented

When a major outcome needs to be communicated

When the content is diverse

Executive Summary is presented just after the cover page, followed by rest of the report

18
 Executive summary
Summary should:
Briefly state the purpose and specific background, if any
Outline the approach to the task, if applicable
Indicate key aspects and salient results
State the main outcomes and/ or conclusions

Summary should NOT:

Provide general information or background
Explain why you are carrying out the design
Provide references to other sections

Be slick, limit it to a page or two. Remember, this is for busy executives!!

19
 Table of contents
Should easily guide the users to the information they
are looking for.

Should be automatically formatted using Microsoft

Word features

Avoid more than 3 sublevels (example – 3.1.1.1, 3.2.3.3)

Number the appendices and state the number of pages

in each appendix

20
Table of contents – an example

21
 Introduction section of the report
This sets the pace for the report, typically split into two
sections:

A project introduction – Ideally, a standard description set

out by the Project

Background information on the specific topic covering

purpose, aims, assumptions etc.

Limit to not more than 2 pages

22
 Body of the report
Key items to remember
Think and mind-map the sections for presenting in a
logical fashion.
Make the headings appropriate and content focused
Use consistent headings to add to the overall impact

Example: Inconsistent headings Example: Consistent

▪ The Company Structure
▪ Do the Communication
Channels Work?
▪ Participating in Groups
▪ How to Develop an Effective
Management Style
headings
▪ Company Structure
▪ Communication Channels
▪ Group Participation
▪ Development of an
Effective Management
Style

23
 Body of the report
Present only relevant information, refer to appendices
for details.
For complex cases, build up the pace.
Avoid repetitions between sections, use consistent
language, number formats and units.

Enhance the quality of the report by

▪ Using figures, tables, graphs and pictures that illustrate
and complement the text.
▪ Using formatting to break up large portions of text
(numbering, bullets etc)
24
 Conclusion of the report

Conclusions should contain the following

Statement of key findings, results or information.

Major outcomes of your investigation and their

significance.

Recommendations and the path forward.

25
 References
Make sure that your referencing method is one that is simple and
consistent.
▪ Include a section for indexing Ref 1, Ref 2 etc. at the beginning or at the end.

Include revision numbers or versions of codes & standards, industry

literature.

Do NOT include revisions for project documents (e.g. PMT

procedures); the latest revision is the default.

Revisit ‘References List’ at each revision of the report.

PDF hyper-linking will add value; review the need on a case-to-case

basis.

26
 Appendices
These should contain material that is too detailed to include in the main
report, such as raw data or detailed drawings.

Each appendix must be given a number (or letter) and title.

Each appendix must be referred to by number (or letter) at the relevant

point in the text.

Number of pages in each appendix should be separately numbered.

As a minimum, the front sheet of the appendix should reference the

main document number (say in the footer).

27
 Equations
Follow conventional style for presenting equations

Centre the equation on the page.

Place the equation number in round brackets at the
right-hand margin.
In the text of your report, refer to equations as either
Eq(1) or equation (1). Then use the chosen format
consistently throughout your report.
List and describe parameters with relevant units

28
 Tables and figures
Conventions for incorporating figures and tables in a report

Usually only two categories are to be used in reports, i.e. tables and
figures

Anything other than tables (maps, charts, diagrams, drawings, graphs)

are to be referred as a figure.

Figures and tables should be placed as close as possible to the point

at which they are referred to in the text.

The title of a table goes above the table, whilst the title of a figure goes
below the figure.

29
 Writing multi disciplinary reports
Ground rules
Assign the overall responsibility to one of the major disciplines for the report.

Splitting the report discipline wise may not be effective.

▪ Ensure full responsibility of sections while coordinating inputs from various
disciplines seamlessly.

Do not leave ‘cut and paste’ paragraphs from different sources unedited.

Do a sanity check and obtain consistency and flow within the document.
▪ Re-run the document with input sources for technical correctness before
submission.

30
 Formatting

Why formatting is important?

Look at it from the reader’s point of view

▪ A correctly formatted document gives an impression that
care has been exercised.

▪ An ill- formatted document may make a reader doubt not just

the formatting skills but more importantly, the technical
content on the report as well.

31
 Quality guidelines

Pay attention to fonts and font sizes.

On tables across pages, use ‘Header Rows Repeat’ feature.

Appropriately superscript and subscript.

m3/h instead of m3/h

Cv instead of Cv

Clarify units unambiguously

Barg or Bara instead of Bar

US or UK gallons

ppmv or ppmw instead of ppm

32
 Quality guidelines
‘Cut and Paste’ without regard to content, tone and blending with
overall report is an absolute NO.

Note that there is a 300 word limitation on ‘Cut and Paste’ from the IHS
contract.

Number all the pages, it should be evident to the reader if something is

missing/ not printed.

Every page within appendices should also be numbered.

Pay attention to logos, use only company and project approved ones.

33
 Quality guidelines

Do NOT pull straight from a printer and submit.

Use grammar check and spell check (MS Word features), but with caution.

Check the physical copy contents manually before submission.

When creating PDFs, derive as much as possible from native files (signed sheets may
be an exception).

Avoid repetition and/or contradictions between sections, use consistent language.

34
 Quality guidelines

Maintain consistency of bullet styles

Avoid headings at the bottom of a page

Check appropriateness of bold/italics, if used

Align both right and left sides of a paragraph to achieve a clean look

Place File name, location and revision in footer

Do not use “&” in the middle of a sentence unless it is part of an abbreviation

35
 Quality guidelines

Acronyms make writing easier, but reading harder.

Stick to full descriptions when you can; use acronyms

judiciously.

Include an index of acronyms, preferably a Definitions

Section in the first few pages.
▪ Give the full description of the text followed by acronym within
parenthesis, the first time you use the acronym in the narrative.

36
 Quality guidelines

Flesch Reading Ease formula gives a score on the readability of a passage.

It’s one of the few accurate measures that can be relied on without too much scrutiny.

It has since become a standard readability formula used by many US Government

agencies including the US Department of Defense.

Primarily, we use the formula to assess the difficulty of reading a passage written in
English.

37
 Quality guidelines

Quality is something whose presence is never

acknowledged but whose absence is always noted

38
 Technical Queries (TQs)
Guidelines on writing an effective TQ

Provide proper references to ITT documents, bid clarifications and/ or global

standards including revision numbers.

Highlight why you are seeking a deviation and how your solution benefits the
project (cost / schedule) and the client (Operations and Maintenance)

Conclude clearly; Ensure your query answers all these questions:

▪ WHY are you seeking the change/ alternative?
▪ HOW will it benefit the project?
▪ HOW will it benefit the client?
▪ WHAT are you recommending?

39
Acknowledgements
Jagadeesh Tayalur
Vasudevasarma
Questions?