TRW Lecture Notes 2017

Technical Report Writing
Technical Report Writing in

Computer Science
© Fekadu Eshetu, Department of Computer Science, Assosa University, Oct, 2017

1. BEFORE YOU START WRITING
 Decide the objective of the report

 Every report should have a single clear objective. Make the
objective as specific as possible.
 Write down the objective.
 Write the objective of the report in one sentence.
 For example, the objective of this course is “to help students
write well structured, easy-to-understand technical reports”.
 The objective should then be stated at the beginning of the
report.
 Always have in mind a specific reader(Audience)
 You should assume that the target reader(student, researcher)
is intelligent but uninformed.
© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

…Cont’d
 Decide what information you need to include.

 You should use the objective as your reference and list the
areas you need to cover.
 Once you have collected the information make a note of each
main point and then sort them into logical groups.
 Make sure that every sentence makes a contribution to the
objective.
 Remove sentences that don’t contribute to the objective
 Have access to a good dictionary.
 Before using a word that ‘sounds good’, but whose meaning
you are not sure of, check it in the dictionary.
 Do the same for any word you are not sure how to spell.

…Cont’d
 Identify someone who can provide feedback.

 Make sure you identify a friend, relative or colleague who can
read at least one draft of your report before you submit it
formally.
 Do not worry if the person does not understand the technical
area – they can at least check the structure and style and it
may even force you to write in the plain English style
advocated here.

…Cont’d
 The following checklist should be applied before you

give even an early draft of your document out for
review:
 Check that the structure conforms to all the rules
described in this document.
 Run the document through a spelling checker.
 Read it through carefully, trying to put yourself in
the shoes of your potential readers.

2. USING PLAIN ENGLISH: STYLE
 If the report is a proposal then you want the reader

to accept your recommendations.
 If the report describes a piece of research then you
want the reader to understand what you did and why
it was important and valid.
 Trying to be ‘clever’ and ‘cryptic’ in the way you write
will confuse and annoy your readers and have the
opposite effect to what you wanted.
 In all cases you are more likely to get results if you
present your ideas and information in the simplest
possible way.

…Cont’d
2.1. SENTENCE AND PARAGRAPH LENGTH

Writing long, complex sentences and paragraphs in technical
writing is simply wrong.
Write reasonably short and simple sentences. In many cases
shorter sentences can be achieved by sticking to the following
principles:
1. A sentence should contain a single unit of information.
Therefore, avoid compound sentences wherever possible. In
particular, be on the lookout for words like and, or and while
which are often used unnecessarily to build a compound
sentence.
2. Check your sentences for faulty construction. Incorrect use
of commas is a common cause of poorly constructed and
excessively long sentences.

…Cont’d
3. Use parentheses sparingly. Most uses are due to laziness and

can be avoided by breaking up the sentence. Never use
nested parentheses if you want to retain your reader.
 Using active rather than passive constructs, will go a long way

toward helping you shorten your sentences.
 A paragraph should contain a single coherent idea.
 You should always keep paragraphs to less than half a page.
 Successive paragraphs that are very short may also be difficult
to read.
 To write a sequence of sentences that each express a different
idea then it is usually best to use bullet points or enumerated
lists to do so.

…Cont’d
2.2. BULLET POINTS AND ENUMERATED LISTS

 If the sentences in a paragraph need to be written
in sequence then this suggests that there is
something that relates them and that they form
some kind of a list.
 The idea that relates them should be used to
introduce the list.
 If what you are describing is a list then you should
always display it as a list (much better to write it
using bullets)

…Cont’d
2.3. USING THE SIMPLEST WORDS AND EXPRESSIONS

POSSIBLE
Clearly use the simplest words and expressions possible.
The golden rules on words and expressions to avoid are:
 Replace difficult words and phrases with simpler alternatives;
 Avoid stock phrases;
 Avoid legal words and pomposity;
 Avoid jargon.

…Cont’d
2.3.1 Replace difficult words and phrases with simpler alternatives

Words and expressions to avoid
Word/expression Simple Word/expression
Simple
to alternative to
alternative
avoid avoid
utilise use endeavour try
facilitate help terminate end, stop
at this time now transmit send
in respect of about demonstrate show
commence start initiate begin
terminate stop, end assist, assistance help

ascertain find out necessitate need
in the event of if in excess of more than
in consequence so dwelling house
enquire ask

…Cont’d
2.3.2 Avoid stock phrases: cumbersome and pompous phrases

Stock Phrases to avoid
BAD GOOD
There is a reasonable expectation that ... ... Probably ...
Owing to the situation that … Because, since …
Should a situation arise where … If …
Taking into consideration such factors as … Considering …
Prior to the occasion when … Before …
At this precise moment in time … Now …
Do not hesitate to … Please …
I am in receipt of … I have …

…Cont’d
2.3.3 Avoid legal words and pomposity

Legal words to avoid
forthwith hereof Of the (4th) inst. thereof

henceforth hereto thereat whereat
hereat herewith therein whereon
Also avoid nonsensical legal references like the following:

1.“The said software compiler…” which should be changed to “The
software compiler…”
2.“The aforementioned people have agreed …”, which should be
changed to “A and B have agreed…”

…Cont’d
2.3.4 Avoid Jargon Words

Jargon refers to descriptions of specific things within a
specialised field.
The descriptions are often shorthand or abbreviations.
Jargon words: RAM, FA Cap ...
Define jargon words the first time you use them in writing
RAM(Random Access Memory)

…Cont’d
2.4. AVOIDING UNNECESSARY WORDS AND REPETITION

Using several words for ideas leads to unnecessarily complex
sentences and genuine redundancy
WITH REDUNDANCY WITHOUT REDUNDANCY
The printer is located adjacent to the The printer is adjacent to the
computer computer
The printer is located in the immediate The printer is near the computer
vicinity of the computer
The user can visibly see the image moving The user can see the image moving
He wore a shirt that was blue in colour He wore a blue shirt
It is likely that problems will arise with You will probably have problems
regards to the completion of the completing the specification phase
specification phase
Within a comparatively short period we will Soon we will be able to finish the
be able to finish the design design

…Cont’d
 Another common cause of redundant words is when people use

so-called modifying words.
BAD GOOD
absolute nonsense nonsense
absolutely critical critical
considerable difficulty difficulty
considerably difficult difficult
suitably impressed impressed
Most common modifying words to avoid

appreciable excessive sufficient definite
approximate fair suitable reasonable
comparative negligible undue utter
evident relative

…Cont’d
2.5. USING VERBS INSTEAD OF NOUNS

Turning verbs into abstract nouns always results in longer sentences than
necessary
BAD GOOD
He used to help in the specification of new He used to help specify new
software software
When you take into consideration … When you consider …
Clicking the icon causes the execution of The program executes when the
the program icon is clicked
Measurement of static software properties The tool measured static software
was performed by the tool properties
The analysis of the software was performed Fred analysed the software
by Fred
The testing of the software was carried out Jane tested the software
by Jane
It was reported by Jones that method x Jones reported that method x
facilitated the utilisation of inspection helped the testing team use
techniques by the testing team inspection techniques

…Cont’d
2.6. USING ACTIVE RATHER THAN PASSIVE STYLE

Joe tested the software – Active voice
The software was tested by Joe – Passive voice
BAD GOOD
The report was written by Bloggs, and was Bloggs wrote the report, and it was
found to be excellent excellent
The values were measured automatically by The control system measured the
the control system values automatically
It was reported by the manager that the The manager reported that the
project was in trouble project was in trouble
The precise mechanism responsible for this We do not know what causes this
antagonism cannot be elucidated antagonism
The stability of the process is enhanced by Co-operation improves the stability
co-operation of the process

…Cont’d
2.7. USING PERSONAL RATHER THAN IMPERSONAL STYLE

“My results have shown…”, first person, personal style
“The author’s results have shown…”, third person, impersonal style
BAD GOOD
The current research work of the author of I also describe my current research
this report is also described work
In the previous report of the authors the In our previous report we discussed
rationale for the proposed method was in detail the rationale for the
discussed in detail proposed method
However, it is the writer’s belief that this However, I believe this situation
situation should not have occurred should not have occurred
Examination and discussion of the results We must examine and discuss the
obtained, are necessary before a decision results before we decide
can be taken

…Cont’d
2.8. EXPLAIN NEW IDEAS CLEARLY

3 techniques to introduce or explain a new idea or abstract
concept
1.Use examples:
 provide an example before providing an abstract definition or
generalization
2.Use analogies:
 email was much like sending a letter, but without stamp
lUse a diagram:
 provide a simple diagram that captures an abstract concept
(very effective if done well).

…Cont’d
2.9. USE CONSISTENT NAMING OF THE SAME ‘THINGS’

 Always use the same word to refer to the same thing.
 Anything else causes confusion and annoyance to readers.
 The project, The system, The plan, …
2.10. PAINLESS POLITICAL CORRECTNESS

 If you are writing manual “how to impress the boss”
 Avoid ‘he’, ‘she’, ‘him’, ‘her’, when referring to non-specific
people
 Use plural pronouns instead of singular.
 Thus, use ‘they’ in place of ‘he’ or ‘she’, use the pronoun ‘them’
in place of ‘him’ or ‘her’, and use the pronoun ‘their’ in place of
‘his’ and ‘her’.
 Avoid any reference to awkward pronouns.

…Cont’d
2.11. SUMMARY
The main points you should have learnt(in order of importance)
are:
Keep sentences and paragraphs short.
Never use a complicated word or phrase when there is a simpler
alternative.
Remove any unnecessary words and repetition.
Use active rather than passive style.
Use active verbs rather than abstract nouns.
Use personal rather than impersonal style.
Explain new ideas clearly by using examples, analogies, and
diagrams.
If what you are describing is a list then use an enumerated list or
bullet points.
…Cont’d
 Avoid stock phrases, legal words and pomposity.

 For each abstract ‘thing’ referred to in your report, use a
consistent name to refer to the ‘thing’.
 In other words ignore the ‘rule’ that says you should never
use the same word twice.
 Use of ‘he’ or ‘she’ to refer to non-specific people is regarded as
politically incorrect and is easy to avoid.
 Never use the words utilise or facilitate since these are
respectively the most useless and pompous words in the English
language.

3. Using Plain English: The Mechanics
3.1 AVOIDING COMMON VOCABULARY AND SPELLING ERRORS

Make sure you always use and spell words correctly.

…Cont’d
 Commonly misspelt words

 accommodate embarrass necessary
 commemorate gauge parallel
 commitment harass privilege
 committee mileage questionnaire
 The final class of vocabulary problems you should avoid is
using American spelling (unless you are submitting your report
to an American audience).
 This means in particular:
 Verbs should end in ‘ise’ rather than ‘ize’ as in ‘generalise’
rather than ‘generalize’ and ‘formalise’ rather than ‘formalize’.
 Words like ‘colour’ and ‘flavour’ should not be written as
‘color’ and ‘flavor’.

…Cont’d
 3.2 ABBREVIATIONS
 The rules you should follow on abbreviations are:
 Always avoid abbreviating words out of laziness. For
example:
 Never write ‘approx.’ for ‘approximately’ (it may be better to
write ‘about’);
 Never write ‘e.g.’ for ‘for example’.
 An exception, but misused example, is ‘etc.’. In most
case where ‘etc.’ is used with such as ….

…Cont’d
 A long title, such as Tottenham Hotspur Football Club,

should not be abbreviated if it is used only once in a
document. However, if it is used more than once then it
can be abbreviated to its initials THFC providing that the
first time it is used you write the full title with the initials
in brackets or vice versa.
 Where initials such as THFC are used as above it is useful
to provide a glossary.

…Cont’d
3.3 PUNCTUATION
Rules for using: Capital letters, Apostrophes, Commas,
Exclamation marks.
3.3.1. Capital Letters: Use capitals for:
 Beginning of sentences, and proper names
 Organisations and places;
 North, South, East and West when they form part of a
country name but not otherwise (hence South Africa, but
south London);
 Titles when used with the name but not otherwise (hence the
Duke of York, but not the duke);
 Certain periods of history (for example, the Black Death,
Renaissance);
 God.
…Cont’d
3.3.2 Apostrophes
Apostrophes have two purposes only:
1.To show that a letter has been missed out:
 For example, isn’t (is not), can’t (cannot), it’s (it is).
2. To show possession:
 For example, the snake’s eyes, the child’s shoes.
 If the thing doing the possessing already has an s at the end
then do not add an s.
 For example, if we are talking about the eyes of several
snakes then we write: the snakes’ eyes.
The only exception to this last rule is if:
 it is a proper noun (Mr Jones’s daughter);
 the word ends in a double ss (the boss’s office).

…Cont’d
 Never use an apostrophe with a possessive pronoun like her, its,

theirs, ours.
 The following examples are wrong (yet they are extremely
common):
 I gave the cat it’s food
 I like tomatoe’s
 In the 1960’s
 All the department’s were represented.
 In each case the apostrophe should not be there.
 A related mistake, which is appalling in its stupidity yet
incredibly common, is:
 I should of done my homework, instead of
 I should’ve done my homework (short for should have).

…Cont’d
3.3.3 Commas
Use fewer commas because you are writing shorter sentences.
Four reasons for using a comma:
 Where you are writing a list.
 Where you are using a qualifying word or expression at the
beginning of a sentence, such as However, For example,
Unfortunately, ...
 Where the sentence would be ambiguous without it. For
example, I decided on an alteration, of course”
 To show where you have inserted a phrase. For example,
“Ronaldo, who is normally the best in the team, had a very
poor match.”
The sentence should still make sense if you remove the part
between the commas.
…Cont’d
3.3.4 Exclamation marks

There are only two reasons ever to use an exclamation mark:
1.Where there is an exclamation as in “Do it now!”, “Help!”
2.As the mathematical notation for the factorial function, as in
“the number 4! is equal to the number 24”
Never use an exclamation mark at the end of a sentence to
indicate that the sentence was supposed to be funny.

…Cont’d
3.4 SUMMARY
The only certain way to avoid spelling errors and incorrect vocabulary is
to use a dictionary whenever you are unsure of anything. However, there
are common examples of words that cause errors and you can learn these.
Use English rather than American spelling unless you are targeting an
American audience.
Abbreviations should be used only where necessary.
Apostrophes should only be used to show possession or to show that a
letter has been missed out. All other uses (especially when used before the
‘s’ in plurals) are wrong.
There are simple rules to learn for when to use commas. In general,
however, writing shorter sentences means using fewer commas.
Apart from its special use in mathematics you should only use an
exclamation mark in an exclamation. Never use it to tell the reader that a
sentence was supposed to be funny.

4. BASIC STRUCTURE FOR REPORTS
4.1 WHAT EVERY REPORT SHOULD CONTAIN

Make sure every report contains the following basic information:
 Title
 Author name(s), affiliation and contact details
 Date
 Version number
 Abstract (if more than 5 pages), which is essentially an
executive summary
 Page numbers
 Table of contents (if more than 10 pages)
 Conclusions(if more than 5 pages)
The first four items above must appear on the front page.
The abstract can appear on the front page or before the table of
contents.
…Cont’d
4.2 GENERAL LAYOUT

Try to make your report attractive to look at.
Stick to the following principles about fonts, spacing and margins
Fonts: Apart from headings and caption labels, you should generally
use the same font and font size throughout. The Times New Roman
font at 11pt or 12pt is a good choice.
Spacing: It is good to have plenty of white space on a page.
 Always leave spaces between paragraphs. (Add Paragraph
Spacing After to 6pt in Microsoft Word - Automatic)
 Avoid using the carriage return to create space between
paragraphs
Margins: Leave wide margins (1.25in is good). For formal reports it
is also best to use the ‘right justify’.

…Cont’d
4.3 SECTIONS AND SECTION NUMBERING

Any report longer than four pages should be broken up into
sections using the following principles:
 Sections should be numbered (preferably using numerals. 1, 2,
3, ..). Whatever numbering convention you use you must be
consistent.
 Each section should have a proper heading that accurately
reflects the material contained within it.
 Long sections should be broken up into subsections, which
should be numbered n.1, n.2, etc. where n is the section
number.
 Long subsections should be broken up into sub subsections
which should be numbered n.m.1, n.m.2, etc where n is the
section number, m is the subsection number.

…Cont’d
 Never use numbered decomposition smaller than sub subsections.

Instead, use bullet points, itemised lists, numbered lists,
numbered examples, etc.
 At every level of decomposition there must always be AT LEAST
TWO components.
 So it is acceptable to have some sections without any

subsections.

…Cont’d
4.4 THE CRUCIAL ROLE OF ‘INTRODUCTIONS’ AND

SUMMARIES
The nature of ‘introductions’ at different levels of decomposition:
The first section of any report should be an introduction and
overview of the entire report. It should end by giving a walkthrough
of the subsequent sections.
Where a section is broken into subsections the text immediately
before the first subsection should be an introduction and overview
of the entire section. It should end by giving a walkthrough of the
subsequent subsections.
Where a subsection is broken into subsubsections the text
immediately before the first subsubsection should be an
introduction and overview of the entire subsection. It should end by
giving a walkthrough of the subsequent subsubsections.

…Cont’d
4.5 FIGURES AND TABLES

It is good to include figures and tables in your document because
they break up the text and make it more readable.
When using figures and tables you should stick to the following the
rules:
 Every figure and table in your document should be numbered
and labelled(Microsoft Word has very good features for
handling numbering automatically)
 Every reference to a figure or table should use the number of
the figure or table.
 Every figure or table that appears in a technical document
must be cited at some point in the document (this is a
consistency requirement).

…Cont’d
4.6 SUMMARY AND CHECKLIST FOR WHEN YOU FINISH WRITING

The following checklist should be applied before you give even an
early draft of your document out for review:
 Check that the structure conforms to all the rules described
above.
 Read it through carefully, trying to put yourself in the shoes
of your potential readers.
 Run the document through a spelling checker.
 Make sure you generate an up to date table of contents and
references to figure and table numbers (selecting all the text
and pressing the F9 key in MS Word should do all of this for
you).

…Cont’d
7. SUMMARY AND CONCLUSIONS

The simpler and shorter you make things, the more likely you are
to produce technical reports that get results.
The Crucial Points:
Have a clear objective in mind before you start writing and make
sure that everything you write is geared towards that objective
alone.
Keep things as simple as possible by using language that is concrete
and familiar.
Keep sentences and paragraphs short.
Avoid long, pompous words and phrases when there is a short
simple alternative (especially avoid the words: utilise, facilitate,
endeavour, necessitate, render).
Avoid unnecessary words, clichés and legal words.

…Cont’d
 Avoid repetition.
 Use active rather than passive style.
 Do not turn verbs into nouns.
 Use personal rather than impersonal style.
 Always refer to the same ‘thing’ in exactly the same way.
 Make sure all reports conform to the basic structure described
(title page with appropriate details, page numbers, appropriate
section numbering, and introductions and summaries where
appropriate).
 Use examples and analogies before introducing abstract concepts.
 Use a dictionary, and make sure you learn the words that are
commonly miss-spelt or misused;
 Write informative (rather than descriptive) abstracts.

…Cont’d
 If your writing includes mathematical symbols and formulas

follow the rules about how these should be displayed.
 Finally, once you have checked that your report conforms
to the principles described here, have a friend whom you
trust read through your report before you submit it. Act
on their recommendations, because they are likely to find
the same problems that your intended audience would.

Thank You!

TRW Lecture Notes 2017

Uploaded by

Copyright:

Available Formats

TRW Lecture Notes 2017

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TRW Lecture Notes 2017

Uploaded by

Copyright:

Available Formats

Technical Report Writing

Technical Report Writing in

© Fekadu Eshetu, Department of Computer Science, Assosa University, Oct, 2017

 Decide the objective of the report

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 Decide what information you need to include.

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 Identify someone who can provide feedback.

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 The following checklist should be applied before you

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 If the report is a proposal then you want the reader

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.1. SENTENCE AND PARAGRAPH LENGTH

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

3. Use parentheses sparingly. Most uses are due to laziness and

 Using active rather than passive constructs, will go a long way

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.2. BULLET POINTS AND ENUMERATED LISTS

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.3. USING THE SIMPLEST WORDS AND EXPRESSIONS

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2017

2.3.1 Replace difficult words and phrases with simpler alternatives

terminate stop, end assist, assistance help

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.3.2 Avoid stock phrases: cumbersome and pompous phrases

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.3.3 Avoid legal words and pomposity

forthwith hereof Of the (4th) inst. thereof

hereat herewith therein whereon

Also avoid nonsensical legal references like the following:

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.3.4 Avoid Jargon Words

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.4. AVOIDING UNNECESSARY WORDS AND REPETITION

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 Another common cause of redundant words is when people use

Most common modifying words to avoid

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.5. USING VERBS INSTEAD OF NOUNS

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.6. USING ACTIVE RATHER THAN PASSIVE STYLE

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.7. USING PERSONAL RATHER THAN IMPERSONAL STYLE

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.8. EXPLAIN NEW IDEAS CLEARLY

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

2.9. USE CONSISTENT NAMING OF THE SAME ‘THINGS’

2.10. PAINLESS POLITICAL CORRECTNESS

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 Avoid stock phrases, legal words and pomposity.

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

3.1 AVOIDING COMMON VOCABULARY AND SPELLING ERRORS

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 Commonly misspelt words

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

 A long title, such as Tottenham Hotspur Football Club,

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016

© Fekadu Eshetu, Department of Computer Science, Assosa University, Nov, 2016