introduction to technical writing and the msc dissertation. alison cawsey (lecturer/textbook writer)...
TRANSCRIPT
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 deliverableAlready discussed by Andy Harvey last week.1. An abstract (about 200 words)
2. Aims and objectives of your project ( 2 or more paragraphs)
3. A project description, rationale and user requirements as appropriate to the project (1,000-2,000 words)
4. An outline of the dissertation structure and layout.
5. A literature review or other background material agreed with your supervisor. (about 5000 words)
6. A statement on professional, legal, ethical and social issues.
7. 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 structuresSE Project1. Introduction2. Background3. Requirements4. Design5. Implementation6. Evaluation7. 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: “In the last chapter it was shown that…This chapter goes on to develop ….”
Consider having a conclusion section to each chapter (except 1st)
Research Project1. Introduction2. Literature Review3. Experimental Design4. Results5. Discussion6. Conclusion
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 “The tools we ues are intimately conectted with our roles as
technical communication professionals.” But they struggle to recognise common errors
“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 e.g. zero, three, eight
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. 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 e.g. about three years; two orders of magnitude; a few tens
of megahertz Use figures when mathematical operations are
implied 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 Avoid ambiguous words such as “small”, “lowest”, “cleaner”
International scientific and engineering standards advise against using commas in numbers of three or more digits (e.g. 1,000) 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 heart-
healthy, 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
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.
Compare the following examples which is clearer? Why is it clearer?
Example 2
The 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 No longer than 10% of the length (for dissertation, ½ to 1 page)
Conveys specific information 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
Unless you can learn it during the course of your project
Make your point and move on Avoid padding
Double check your work
Reading
Technical Writing http://www.utoronto.ca/writing/advise.html 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