introduction to technical writing and the msc dissertation. alison cawsey (lecturer/textbook writer)...

37
Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

Upload: garry-johnston

Post on 21-Dec-2015

219 views

Category:

Documents


2 download

TRANSCRIPT

Page 1: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

Introduction to Technical Writing and the MSc Dissertation.

Alison Cawsey (lecturer/textbook writer)

Joanne Murphy (technical writer)

Page 2: 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.

Page 3: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 4: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 5: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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].

Page 6: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.

Page 7: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.

Page 8: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 9: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.

Page 10: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.”

Page 11: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 12: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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).

Page 13: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 14: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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…

Page 15: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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?

Page 16: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 17: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 18: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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”

Page 19: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 20: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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”

Page 21: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 22: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 23: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 24: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.”

Page 25: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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”

Page 26: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 27: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.”

Page 28: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 29: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 30: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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.

Page 31: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 32: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 33: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 34: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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!

Page 35: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 36: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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

Page 37: Introduction to Technical Writing and the MSc Dissertation. Alison Cawsey (lecturer/textbook writer) Joanne Murphy (technical writer)

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