Technical Style Handbook
68
Technical Style A 2-part introductory workshop Presented by Edwin Hollon for Kyung Hee University - Suwon, South Korea
-
Upload
eddie-hollon -
Category
Business
-
view
4.456 -
download
2
description
A handbook to accompany the 2-part introductory workshop on style in technical communication. Provided to beginning technical writing students at Kyung Hee University in Suwon, South Korea.
Transcript of Technical Style Handbook
Technical StyleA 2-part introductory workshop
Presented by Edwin Hollon for Kyung Hee University - Suwon, South Korea
Introduction- What is Technical Style?
When you think of the word style, what comes to mind? Perhaps you think of the latest clothes fashions or maybe automobile designs. These are fine examples, but this is a class about technical writing. So, how does style apply in this context?
As students, most of you are probably familiar with some sort of style guide, such as the Chicago Manual of Style. These types of guides contain lots of rules and conventions to help authors write consistently and follow grammar rules. So, is this what I mean when I say “technical style?” Not exactly.
Of course, technical writers must pay close attention to grammar rules. They must follow all types of conventions and grammatical rules when they write. However, the subject of this workshop—“technical style”—is about more than just grammatical rules and conventions.
Technical style involves some of the most important considerations of technical writing. That is, how to effectively communicate with your audience. In this 2-day workshop, we will discuss some basic principles of technical style that will help you write more accurately, more clearly, and more concisely. In addition, we will talk about how and when to use technical terminology and tips for proper use of commonly misused words. Finally, we will discuss the importance of style guides, how to use them, and even how create basic style guides for your writing projects.
To learn more about style…
This workshop is based in part on Joseph M. Williams’ book Style: Ten Lessons in Clarity and Grace (8th edition). Because this is an introductory course, we will only briefly look at a few of the principles of style covered by Mr. Williams. However, if you would like to learn more about this topic, Mr. Williams’ book is an excellent resource.
About me…
My name is Edwin Hollon and I am a professional technical communicator. I completed my Bachelor’s degree in English composition and my master’s degree in Technical Writing. I have worked as a technical writer in several different fields, including IT, defense contracting, and consumer electronics.
For the last 3 years, I have worked here in Suwon developing user guidance, providing professional education and lectures about technical writing, helping to promote and expand the industry, and managing a wide variety of information projects. If you would like to learn more about my experiences as a technical communicator, you can view my professional profile online: www.linkedin.com/in/eddiehollon
On the cover: “Clip Language Clip & Tiepin” by Koo, Jin-woog and Sim Mi-so, 2007.
Rhetorical Situation
The rhetorical situation includes the audience (who we are writing for), the purpose (why we are writing to them), and the occasion (when, where, and how the audience will receive our message.
Based on the rhetorical situation, we can make decision about the appropriate style, tone, and delivery method for our message. In the table below, consider the rhetorical situation (audience, purpose, and occasion) and then choose the appropriate message.
Audience Purpose Occasion Message
Retired travelers
Promote travel sales
Anytime during travel season
Electronic specifications file sent by email
Mobile phone users
Instructions for new functions
As needed when using the phone
Printed fliers placed in mailboxes
Residents of apartment building
Notify about new water policy
One month before effective date
Television advertisement during scheduled programming
Aerospace engineers
Update physical specifications of parts
Before rush deadline
Help system embedded in the mobile phone
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 1 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
2 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 3 of 34
________________
________________
________________
________________
________________
________________
________________
________________
4 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 5 of 34
________________
________________
________________
________________
________________
________________
________________
________________
6 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 7 of 34
________________
________________
________________
________________
________________
________________
________________
________________
8 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 9 of 34
________________
________________
________________
________________
________________
________________
________________
________________
________________
10 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 11 of 34
________________
________________
________________
________________
________________
________________
________________
________________
12 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 13 of 34
________________
________________
________________
________________
________________
________________
________________
________________
14 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 15 of 34
________________
________________
________________
________________
________________
________________
________________
________________
16 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 17 of 34
________________
________________
________________
________________
________________
________________
________________
________________
18 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 19 of 34
________________
________________
________________
________________
________________
________________
________________
________________
20 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 21 of 34
________________
________________
________________
________________
________________
________________
________________
________________
22 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 23 of 34
________________
________________
________________
________________
________________
________________
________________
________________
24 of 34 Technical Style – A 2-day Introductory Workshop
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 25 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
26 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 27 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
28 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 29 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
30 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 31 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
32 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 33 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
34 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 35 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
36 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 37 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
38 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 39 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
40 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 41 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
42 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 43 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
44 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 45 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
46 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 47 of 34
Notes
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
________________
48 of 34 Technical Style – A 2-day Introductory Workshop
________________
________________
________________
________________
________________
________________
________________
________________
Technical Style – A 2-day Introductory Workshop 49 of 34
Appendix A – Commonly Misused Words
This is a condensed list of some commonly misused words. Refer to the reference section to find more examples online.
accept and except
While they sound similar, except is a preposition that means "apart from", while accept is a verb that means "agree with", "take in", or "receive". Except is also rarely used as a verb, meaning to leave out.
We accept all major credit cards, except Diners Club.
Men are fools... present company excepted! (Which means, "present company excluded")
I had trouble making friends with them; I never felt excepted.
We all went swimming, accept for Jack.
affect and effect
The verb affect means "to influence something", and the noun effect means "the result of". Effect can also be a verb that means "to cause [something] to be", while affect as a noun has technical meanings in psychology, music, and aesthetic theory: an emotion or subjectively experienced feeling.
This poem affected me so much that I cried.
Temperature has an effect on reaction spontaneity.
The dynamite effected the wall's collapse.
He seemed completely devoid of affect.
The rain effected our plans for the day.
We tried appeasing the rain gods, but to no affect.
assure, ensure, and insure
To assure is to intend to give the listener confidence, to ensure is to make certain of, and to insure is to purchase insurance.
I assure you that I will have your car washed by the time you return.
When you mow the lawn, ensure there are no foreign objects in the grass.
I plan to purchase the collision policy when I insure my car.
can't and cant
Can't is a contraction of cannot. Cant has a number of different meanings, including a slope or slant, or a kind of slang or jargon spoken by a particular group of people. "Canting arms" is a coat-of-arms that represents meaning of the bearer's surname.
I can't understand the dialogue in this book because it is written in cant.
Heralds do not pun; they cant.
I cant swim; I have never taken lessons.
50 of 34 Technical Style – A 2-day Introductory Workshop
complementary and complimentary
Things or people that go together well are complementary, whereas complimentary refers to a free bonus gift item or giving someone a compliment.
Orange and blue are complementary colors.
This sales item comes with a complimentary gift.
Jane was very complimentary about your new home.
contiguous, continual, and continuous
Contiguous means "touching" or "adjoining in space"; continual means "repeated in rapid succession"; continuous means "uninterrupted" (in time or space).
Alaska is not one of the forty-eight contiguous states.
The field was surrounded by a continuous fence.
The continuous murmur of the stream.
His continual interruptions are very irritating.
disassemble and dissemble
To disassemble means "to dismantle" (e.g. to take a machine code program apart to see how it works); to dissemble means "to tell lies".
discreet and discrete
Discrete means "having separate parts", as opposed to contiguous. Discreet means "cautious".
economic and economical
Economic means "having to do with the economy". Economical means "financially prudent, frugal" and also figuratively in the sense "sparing use" (of time, language, etc.)[1]
Buying in bulk can often be the most economical choice.
The actor should be economical in his use of movement.
He attended the School of Economic and Business Sciences.
Leading economical indicators suggest that a recession may be on the horizon.
The actor should be economic in his use of movement.
e.g. and i.e.
The abbreviation e.g. stands for the Latin exempli gratiā "for example", and should be used when the example(s) given are just one or a few of many. The abbreviation i.e. stands for the Latin id est "that is", and is used to give the only example(s) or to otherwise qualify the statement just made.
A Briton is a British citizen, e.g. John Lennon.
Tolkien's The Hobbit is named after its protagonist, i.e., Bilbo Baggins.
A Briton is a British citizen, i.e., Paul McCartney (at the last count, there were about 60 million Britons—Sir Paul is far from being the only one)
Technical Style – A 2-day Introductory Workshop 51 of 34
emigration and immigration
Emigration is the process of leaving a country; immigration is the process of arriving in a country—in both cases, indefinitely.
Ethnic communities, such as Little Italy, were created by people emigrating from their home countries.
historic and historical
In strict usage, historic describes an event of importance—one that shaped history or is likely to do so. Historical merely describes something that happened in the past.
The president made a(n) historic announcement. (The announcement was of historical importance.)
The office kept an archive of historic records. (The records are not necessarily of historical importance—they are simply records from the past.)
imply and infer
Something is implied if it is a suggestion intended by the person speaking, whereas a conclusion is inferred if it is reached by the person listening.
When Tony told me he had no money, he was implying that I should give him some.
When Tony told me he had no money, I inferred that I should give him some.
When Tony told me he had no money, he was inferring that I should give him some.
it's and its
It's is a contraction that replaces it is or it has (see apostrophe). Its is the possessive determiner corresponding to it, meaning "belonging to it".
It's time to eat!
My cell phone has poor reception because its antenna is broken.
It's been nice getting to meet you.
Its good to be the king.
The bicycle tire had lost all of it's pressure.
isle and aisle
An isle is a small island in a string of small islands. An Aisle is corridor through which one may pass from one place to another.
He came from a small isle in the Caribbean.
The coffee is down the third aisle on the left.
52 of 34 Technical Style – A 2-day Introductory Workshop
lay and lie
lay (lay, laid, laid, laying) and lie (lie, lay, lain, lying) are often used synonymously. Lay is a transitive verb, meaning that it takes an object. "To lay something" means to place something. Lie, on the other hand, is intransitive and means to recline (and also to tell untruths, but in this case the verb is regular and causes no confusion). The distinction between these related verbs is further blurred by the fact that past tense of lie is lay. An easy rule of thumb is to replace the words with sit and set. If sit makes sense (e.g. sit down) then lie should be used (lie down). If the sentence works with set (e.g. set the book on the table) then lay should be used (lay the book on the table). To lie can also mean "to not tell the truth" - but in that case, the past tense is lied. A layoff is never a lieoff or lyoff.
I lay my husband's work clothes out for him every morning. Yesterday, I decided to see if he paid attention to what I was doing, so I laid out one white sock and one black. He did not notice!
You should not lie down right after eating a large meal. Yesterday, I lay on my bed for half an hour after dinner, and suffered indigestion as a result. My wife saw me lying there and made me get up; she told me that if I had waited for a couple of hours I could have lain down in perfect comfort.
You lied to me, there is no hidden chamber!
Is this bed comfortable when you lay on it? (Should be lie)
Yesterday I lied down in my office during the lunch hour. (Should be lay)
There was no reason for him to have laid down in the middle of the path, it unnerved me to see him laying there saying nothing. (Should be "have lain down" and "him lying there")
Lie the baby down, and change his diaper (Should be lay, as lie is intransitive)
"It could be easy for those guys to lay down. After I left, they could have just laid down."[2]
I am going to lay out in the sun and work on my tan. (Should be lie. In general, the term lay out when referring to sunbathing is always non-standard usage.)
Sorry, I lay about our appointment yesterday. (Should be lied)
lose and loose
Lose can mean "fail to win", "misplace", or "cease to be in possession". Loose can mean the opposite of tight, or the opposite of tighten. Lose is often misspelled loose, likely because lose has an irregular rhyme for the way it is spelled: it is more common for words ending -ose to rhyme with nose, or rose, but lose rhymes news or confuse. This may cause poor spellers to guess the correct spelling should match another rhyming word like choose, although choose is itself also an exception to the regular rhyme for words ending -oose (typically such words, including loose, rhyme with goose or caboose).
We cannot afford to lose customers to our competitors.
A screw is loose and I need a wrench to tighten it.
If the team cannot score any points, they will loose the game.
Technical Style – A 2-day Introductory Workshop 53 of 34
past and passed
Past refers to events that have previously occurred, while passed is the past tense of "to pass", whether in a congressional action or a physical occurrence.
Congress passed the bill limiting the powers of the President.
History is mainly concerned with the events of the past.
He past my house on his way to the store.
set and sit
When used as a verb, to set means "to place" or "to adjust to a value", whereas to sit means, "to be seated".
Set the pot upon the stove.
Set the temperature-control to 100 °C.
Sit on the chair.
Set down over there.
Sit the pot on the stove.
than and then
Than is a grammatical particle and preposition associated with comparatives, whereas then is an adverb and a noun. In certain dialects, the two words are usually homophones because they are function words with reduced vowels, and this may cause speakers to confuse them.
I like pizza more than lasagne.
We ate dinner and then went to the movies.
You are a better person then I am.
there, their, they're, and there're
There refers to the location of something. Their means "belonging to them". They're is a contraction of "They are". There're is a contraction of "there are".[citation needed]
There're five of them and they're all coming to the restaurant for their dinner; we will meet them there.
whose and who's
Whose is an interrogative word (Whose is this?) or a relative pronoun (The people whose house you admired); who's is a contraction for "who is" or "who has".
54 of 34 Technical Style – A 2-day Introductory Workshop
won't and wont
Won't is a contraction for "will not", while wont is a word meaning "accustomed" or "inclined to" (as an adjective) or "habit or custom" (as a noun).
He won't let me drive his car.
He spent the morning reading, as he was wont to do.
He took a walk in the evening, as was his wont.
I wont need to go to the supermarket after all.
you're and your
While they sound the same in many dialects, in standard written English they have separate meanings. You're is a contraction for "you are", and your is a possessive pronoun meaning "belonging to you". When in doubt, just see whether the word in question can logically be expanded to "you are".
When driving, always wear your seatbelt.
If you're going out, please be home by ten o'clock.
You're mother called this morning.
Your the first person to notice my new haircut today!
Technical Style – A 2-day Introductory Workshop 55 of 34
Appendix B – References
Print Resources
Cambridge Learner’s Dictionary (2nd Edition) – Cambridge University Press
Cambridge Advanced Learner’s Dictionary (3rd Edition) – Cambridge University Press
A Writer’s Reference (6th Edition) – Diana Hacker
The Global English Style Guide: Writing Clear, Translatable Documentation for a Global Market – John R. Kohl
Style: Ten Lessons in Clarity and Grace (8th Edition) – Joseph M. Williams
Read Me First! A Style Guide for the Computer Industry (2nd Edition) – Sun Technical Publications
Microsoft Manual of Style for Technical Publications (3rd Edition) – Microsoft Corporation Editorial Style Board
56 of 34 Technical Style – A 2-day Introductory Workshop
Online Resources
A Writer’s Reference online companion site – an online version of Diana Hacker’s style guide. (http://www.bedfordstmartins.com/hacker/writersref/)
Brian’s list of common errors in English usage – an excellent collection of common problems with English usage, including commonly misused words, commonly misspelled words, and frequently misunderstood grammatical rules. (http://www.wsu.edu:8080/~brians/errors/index.html)
Strunk & White’s “Words and Expressions Commonly Misused” – an excerpted section from the classic book on English style. (http://www.bartleby.com/141/strunk3.html)
Wikipedia’s list of differences in meanings between British and American English – a comprehensive list of words and their different meanings in the UK and US. (http://en.wikipedia.org/wiki/List_of_words_having_different_meanings_in_British_and_American_English)
Wikipedia’s list of commonly misused English words – a collection of common mistakes in usage that includes good examples of standard and non-standard usage. (http://en.wikipedia.org/wiki/List_of_commonly_misused_English_words)
Wikipedia’s list of commonly misspelled English words – a collection of common mistakes in spelling. (http://en.wikipedia.org/wiki/Wikipedia:List_of_common_misspellings)
Technical Style – A 2-day Introductory Workshop 57 of 34
