Introduction to Technical
Writing and the MSc
Dissertation.
Alison Cawsey
(lecturer/textbook writer)
Joanne Murphy
(technical writer)
Aim of Session

To clarify what is expected in the MSc
Dissertation documents.




Research Methods deliverable, due end May.
Main project report, due 6th Sept
To suggest possible structures for that
document and ways of organising your
material.
To discuss general principles for good
technical writing.
Research methods deliverable
Already discussed by Andy Harvey last week.
1.
2.
3.
4.
5.
6.
7.
An abstract (about 200 words)
Aims and objectives of your project ( 2 or more paragraphs)
A project description, rationale and user requirements as
appropriate to the project (1,000-2,000 words)
An outline of the dissertation structure and layout.
A literature review or other background material agreed with your
supervisor. (about 5000 words)
A statement on professional, legal, ethical and social issues.
A conclusion and discussion of the issues for your project
MSc Dissertation


15,000-20,000 words (about 60 pages)
Containing:

Title page
Declaration that it is your own work.
Abstract (see later)
Acknowledgements
Table of contents

Main Dissertation Content (the chapters)

References
Appendices





Main Points to Consider:




How to write an abstract.
How to select and organise your material and
structure your material into chapters.
How to “pitch” your material, and make your
arguments clear.
How to refer to and build on related work in
the field [covered in session on Literature Review last week;
also next weeks session on attribution].
Pitching it at the right level

Your project will be assessed primarily from the
dissertation – so it is essential that it is a full account
of the work and is clearly presented.


Marked by supervisor and a second reader, and sometimes
moderated by third reader and/or extrernal examiner.
Assume your reader has good general knowledge of
CS/IT, but NOT that they are a specialist in your
topic. Write it so that it would be accessible to a
fellow student.
Getting a good structure


Your document must be coherent – all chapters
contribute to showing how you have achieved your
aims.
General structure (of chapters):




Introduction: State your aims, problem description,
introduce document.
Literature review/background: Show what prior work
contributes to your aims, limitations of that prior work, and
point to how your work will build on this prior work and
advance your aims.
Middle section: Chapters which present your work.
Conclusion/Further work: A final chapter which shows how
you have achieved your aims, reflects on the project and its
limitations, and suggest further work that would be useful.
Two typical structures
SE Project
1. Introduction
2. Background
3. Requirements
4. Design
5. Implementation
6. Evaluation
7. Conclusion


Many variations suitable for different types of project. Discuss
possible structures with your supervisor.
Each chapter should link to the last – you can introduce chapters by
saying something like:


Research Project
1. Introduction
2. Literature Review
3. Experimental Design
4. Results
5. Discussion
6. Conclusion
“In the last chapter it was shown that…This chapter goes on to develop ….”
Consider having a conclusion section to each chapter (except 1st)
Coherence


A good dissertation should be coherent!
The reader should be able to see how:






Every sentence relates to the previous sentence.
Every paragraph relates to the previous paragraph.
Every section relates to the previous section. Etc etc.
These connections/relations may be: example,
elaboration, evidence, background
The connection is often signalled with discourse
markers like “however”, “furthermore”, “for example”,
“in other words”.
It is important to make these connections clear. The
connections often convey crucial implicit information.
Coherence

Each chapter should link to the last – you can introduce
chapters by saying something like:



“In the last chapter it was shown that…This chapter goes on to develop
….”
Consider having a conclusion section to each chapter
(except 1st)
Refer back to previous chapters frequently.



“As was showed in Chapter 2,..”
“A major requirement of the software (described in detail in
chapter 2) was to..
“In chapter 1 the aims of the project were outlined. The main
aim was to X. In this chapter it is shown how X has been
achieved.”
What if your first language is not English?

You must still ensure all of your dissertation is in
your own words,
“Unless it is quoted and cited like this.”
(Cawsey, 2005, p23)


Keep things simple: If you don’t know how to use an
English word correctly, use simpler language
instead.
Get a native speaker to proof read it if possible (your
supervisors job is not to correct the English).

If you need more help, contact the English tutors:
http://www.hw.ac.uk/langWWW/english/courses/eap_is.html
Dissertation Assessment

What are the markers of your dissertation looking
for?








Clear and concise presentation of work
Demonstration of depth of understanding
Coverage of work/knowledge of the field
Quality of any product
Ability to critically analyse other work and to come up with
original analyses and ideas.
Any contribution to knowledge.
Evidence of initiative and perserverance.
Evidence of professional conduct, consideration of any
ethical issues, and NO plagiarism (passing off works of
others as if they are your own).
Style



You will get a higher mark for your
dissertation if it is written in a clear and
effective style!
So next section considers, among other
things, good style for technical writing.
This is a general skill that, once developed,
will be enormously useful in any further
academic or professional work!
What is Style?

“The way in which something is said, done,
expressed, or performed”
(The American Heritage® Dictionary of the English Language, Fourth Edition )


In this case, how it is written and presented
The style you adopt will effect your readers
perception of your work

Your choice in style can engage the reader or put
them to sleep, make them laugh or make them
cry…
Getting Started

What?


What are you writing about? (aims, topic, etc.)
What type of document are you writing?


Research paper? User guide? etc.
Who? (audience analysis)

Who are you writing for?



What do they know?
What do they want to know?
What do they need to know?
Planning

Take a moment to consider the structure of
your document


Plan sections and sub-sections
Plan content



These don’t need to be complete or concrete
The purpose is to help you get going
Don’t become distracted by formatting!


Either define your formatting before you start
Or wait until you’re finished
Words

Spelling and Grammar



Errors can alter the meaning of your work
 “My aunt who lives in London is coming to visit”
 “My aunt, who lives in London, is coming to visit”
 “My ant who lives in London is coming to visit”
Errors can confuse meaning altogether
 “Ten items or less”
Jargon, abbreviations and acronyms


Typically to be avoided
Except where they encompass specialist terms widely
understood by your intended audience

if the definition can’t be found in a good dictionary, don’t use it!
Words (continued)

Using a thesaurus

A useful tool for when you require a more
academic (or simpler) word


Instead of saying “educational background” you might
want to say “pedagogical experience”
However, beware!


A thesaurus suggests words – both relating and
contrasting
However, not all the synonyms listed mean the same
thing

e.g. “side-by-side” and “juxtaposed”
Exercise 1 - Words

Do you know the difference?







Its – It’s
There – Their – They’re
Your – You’re
Lay - Lie
Imply – Infer
Affect – Effect
Eat – Consume
Spelling and Grammar Checking


Spell check your work
Proofread!

Spell checkers can weed out typing errors


But they struggle to recognise common errors


“The tools we ues are intimately conectted with our roles as
technical communication professionals.”
“Eye halve a spelling chequer
It came with my pea sea
It plainly marques four my revue
Miss steaks eye kin knot sea ”
And they often struggle with basic grammar

“The sat cat on the mat”
Numbers

As a general rule, single digit numbers are spelled
out


Whilst numbers of two or more digits are expressed
in figures


e.g. 40, 356, 20th Century
Always use figures for all numbers when there are
numbers of two or more digits of related quantities in
the same sentence


e.g. zero, three, eight
e.g. 3 out 10 housewives recommend Flash
And always use figures when a unit of measurement
follows the number

e.g 5 V, 100 MHz, 5.5 cm
Numbers (continued)

Spell out numbers where the values being
expressed are approximations


Use figures when mathematical operations are
implied


e.g. about three years; two orders of magnitude; a few tens
of megahertz
e.g. factor of 2; 3x3 matrix
And, finally, when a number forms the beginning of a
sentence always spell it out

e.g. Five years earlier…, Twentieth Century technology…,

If the result appears awkward, consider a rewrite!
Numbers (continued)

As a general rule you should look to give a
numerical value in statements


International scientific and engineering standards
advise against using commas in numbers of three or
more digits (e.g. 1,000)


Avoid ambiguous words such as “small”, “lowest”, “cleaner”
In some countries (e.g. Germany) the presence of a
comma in a number indicates a decimal point
Avoid improper addition of numbers!


If John is 23 years old and Mary is 18 years old, do they
have 41 years of life experience between them? No!
If you heat two pots of water to 80oC, is the combined
temperature of both pots 160oC? No!
Exercise 2 - Numbers

Which of the following sentences are correct?





“There are five apples in the basket.”
“All of the fixtures and fittings were salvaged from the Mary
Rose about 20 years ago.”
“Nine out of 10 physicians recommend walking as a hearthealthy, daily exercise.”
“When one litre of water at 100oC is mixed with one litre of
water at 0oC the result is two litres of water at 50oC.”
“When we apply a potential of ten volts to the grid with
respect to the cathode this produces an electric field.”
Voice


“Voice” is the way your words sound
It is expressed in the relationship between
the subject of a sentence and the verb

Active: the agent of the action is the subject of the
sentence


“Birds build nests”
Passive: the receiver of the action is the subject of
the sentence


“Nests are built by birds”
“Nests are built”
Active vs. Passive

An active voice provides clarity and force



It is simple and precise; subjective rather than objective
Good for instructional purposes – commanding
A passive voice shifts emphasis and slows the pace


Often considered longwinded, ambiguous and dull
 The reader can lose sight of any agents
However, scientific and technical writing is often objective
 A passive voice focuses the reader on the process

Shifting the readers attention towards the action receiver
Exercise 3 - Voice

Consider the following sentences






“The dog bit the boy.”
“Mistakes were made.”
“Technical writers produce books and other printed
materials for a variety of audiences.”
“The aurora borealis can be observed in the early morning
hours.”
“Tiny shifts in blood flow to parts of the brain were detected
with functional resonance imaging.”
“The experiment examined the relationship between the
two theories.”
Write in Plain English


Don’t confuse “plain English” with “dumbed
down”
Plain English focuses on the message


It is user friendly
Omit needless words


definitely proved; orange in colour; viable alternative
Avoiding unnecessary jargon, technical
expressions and complexity

It refers to a flexible and efficient writing style that
combines clear, concise expression with effective
structure
Write in Plain English (continued)


Avoid “padding”
Aim to keep your sentences at between 10 to
20 words long

Long sentences make a document difficult to read


Your end reader might soon lose track of your point
If you’re giving instruction stay closer to the 10
word limit

Instructions are best presented as short, sharp
sentences
Exercise 4 – Plain English
 Compare the following examples
 which is clearer? Why is it clearer?
Example 1
Following the media release which
alleged that agricultural chemical
residues posed an unacceptable risk
to children, there was a struggle
between government and consumer
organisations which also involved
the chemicals’ manufacturer
(Uniroyal) and the apple-growing
industry. Consumer fears, which
had been triggered by the debate
over the risk – were mitigated, within
months, by the stopping the use of
the chemicals, as Uniroyal withdrew
the products.
Example
The
2
media release alleged that
children were at risk from agricultural
chemical residues. It provoked a
struggle between government and
consumer organisations, though
Uniroyal (the manufacturer) and
apple-growers were also involved.
Uniroyal withdrew the products within
months, thus stopping the use of the
chemicals. This mitigated any
consumer fears generated by the
debate over the risks.
User Testing


Test your work with the intended reader
We are often poor judges of our own work


As the producer, we lose impartiality
User testing will show up ways to improve
your document


Helps pick up on spelling and grammatical errors
Pins down weaknesses in your argument


Or instructions
Rethink, redesign and rewrite any area that
confused your user
Abstract

The Abstract forms a review of your work





It is a condensed version of the main body of your
work
Highlighting the major points covered
Briefly describing the content and scope
The aim of the abstract is to entice readers to
read your document
It is written after the report has been
completed

Though it is intended to be read first
Abstract (continued)

There are two types of Abstract:

Descriptive Abstract

About 100 words in length


No longer than a paragraph!
It is an introduction to the subject



Identifying information contained within the report
Describing the purpose, methods and scope
Does not provide details of results!
Abstract (continued)

And

Informative Abstract

Length dependent on work being summarised



Conveys specific information



No longer than 10% of the length
(for dissertation, ½ to 1 page)
Summarising the purpose, methods and scope
Indicating results, conclusions and recommendations
Not the same thing as an introduction!
Abstract (continued)

Do not use references in your abstract






If your work is based on the work of some other author, and
this is key to your report, you may invoke them by name
Do not quote!
Avoid repeating or rephrasing the title of your work
Do not refer to any information that is not contained
within your document
It is best to avoid jargon, abbreviations and
acronyms that require explanation
Avoid the temptation to refer to and explain sections
of your report
Things to Remember

Be consistent!


Once you’ve adopted a style, stand by it
Stick to what you know

If you don’t know it avoid it


Make your point and move on


Unless you can learn it during the course of your project
Avoid padding
Double check your work
Reading

Technical Writing

http://www.technical-writing-course.com/
 http://www.rbs0.com/tw.htm
Style
 http://owl.english.purdue.edu/handouts/grammar/g_actpass.html
 http://grammar.ccc.commnet.edu/grammar/passive.htm
 http://grammar.qdnow.com/
Abstracts
 http://www.olemiss.edu/depts/writing_center/grabstract.html
 http://leo.stcloudstate.edu/bizwrite/abstracts.html
 http://www.gmu.edu/departments/writingcenter/handouts/abstract.
html



http://www.utoronto.ca/writing/advise.html