Writing Workshop

Writing Workshop

Topic status automatically displays here - do not remove.

Bookmark me!Bookmark this topic  Print me!Print this topic

Welcome 

[Time: 30 mins]
[Slide: "Writing Workshop"]

Hello

Hello. How are you? Good I hope? I'm Colin Ramsden, the Technical Writer from BenQ Australia, and I'd like to thankyou all for coming here today. Please call me 'Col'. Some of you I've already worked with: Kenny, Effie, Yvette, Debbie; (where are you sitting?)

I bet the rest of you have heard about me? Have you? Don't worry, I'm not here to test your English knowledge, or to try and trick-you-up. I'm not here to replace you, or identify you for replacement. I'm not here to find fault with what you do. I am here however, to help you with your English writing skills, to introduce you to 'world best practice' technical writing principles, and to explore ways to improve our communication, writing, and publication procedures.

Welcome

With your permission, I'd like to welcome you to the inaugural BenQ Technical Writers' Workshop.

As we're going to be spending some time together over the next day or so, I'd like to get to know you better, so until I remember your names, would you please keep your name badges on and visible during the workshop and breaks. We might as well be comfortable whilst we're here, so please help yourselves to the sweets and drinks on the table whenever you feel like it. 

[Handout: Workshop Folders]

Meeting

As a brief introduction to myself and why I am here today before you; I've had many varied work experiences which you may or may not be aware of. Please let me share some of them with you so that you can better understand my background: 

[Slide: (progressive) "Colin Ramsden (FGAA, Dip DT);
electrician, industrial electronic technician, manufacturing jeweller, gemsetter, 
jewellery designer, jewellery valuer, gemmologist, diamond technologist, software developer, 
web developer, technical writer, graphic artist, requirements analyst, help developer, 
procedural writer, knowledge worker, style master, tutor."]

On a personal level, I live on the sunny Central Coast of New South Wales, just one hour north of Sydney, Australia. I have five children now aged from 22 to 3, and currently live with my second wife and 2 youngest in a house on a wooded acre block.  We have a cat and a dog, and an inflatable pool on the back patio for summer; which I've left behind to be with you here today.

That's enough about me. How about you? Do you all know each other? Have you all met? Would you please give me a brief introduction of yourselves, starting with you Kenny. [Discuss briefly around table]

Travel

I travelled over 8000km in 15 hours yesterday. Did you come far? How did you get here? [Discuss briefly around table again]

Rules

We've got a lot to cover in a small amount of time, so we'll need some order and organization to get through it unscathed. There are a few rules I'd like to introduce to the proceedings to keep things going as smoothly as possible. 

[Slide: "Workshop Rules"]

Back to Top

Writing Workshop Agenda 

[Slide: (progressive) "Workshop Agenda"]
  1. Document usability and user identification
  2. Document structure
  3. Document template and style usage
  4. Use of English
  5. Document control and management

Back to Top

Proceedings

"All we have to decide is what to do with the time that is given us." Gandalf The fellowship of the ring.

Back to Top

Session 1:
Document usability and user identification 

[Slide: "Session 1: Document usability and user identification"]
[Handout: Session 1 Notes]

1A: Document usability

[Time: 20 mins]
[Slide: "What is the purpose of writing?"]

Before you write somethinganythingyou should always ask yourself: "What is the purpose of writing?"

You need to know why you are writing and what are you trying to achieve with the writing! 

[Whiteboard: Brainstorming  list ideas  "What is the purpose of writing?" (limit 5 mins)]

  

[Slide: "The primary goal of writing is to communicate effectively."]

If our writing does not communicate effectively, then we're not doing our job.

First and foremost, our writing must be understood. If our readers can't or don't understand what we've written, then we've failed to communicate properly with them. It's not their fault, it's ours!

  

[Slide: "How can we communicate more effectively with our writing?"]

It is our responsibility to communicate effectively. Now how might we go about doing that?
[discuss (limit 5 mins) use whiteboard if necessary to list ideas]

  

[Slide: (progressive) "Useful writing is: written clearly, structured logically, 
ordered sequentially, succinct, easily navigable." (explanations below)]

Our writing must be as useful as possible. It should be:

To achieve this usability, we must write in a way that is understandable to the user, providing information in a logical and sequential order for the user, in just the right amount—without unnecessary elaboration—and in a manner that the user can readily find what they're looking for without frustration.

Is that too much to ask? That our writing be usable and useful to the user? Does anyone disagree?
[discuss briefly]

  

[Slide: "How can we know what is usable and useful to the user?"]

If we are to make our writing usable and useful, how might we go about doing that?
[discuss (limit 5 mins) use whiteboard if necessary to list ideas]

  

[Slide: "Who is the user of our writing?"]

We need to identify the users of our writing, so that we can focus our efforts toward providing them with useful and usable information.

  

[Slide: "The primary goal of writing is to communicate effectively."]

Only then can we expect to achieve effective communication. And isn't that our primary goal?

Back to Top

User identification

[Time: 20 mins]
[Slide: "User identification"]

The needs and expectations of the users of our writing must be considered if they are expected to be able to read, understand and use the information in the way the writer intends.

  

[Slide: "Reverse your view. You are not writing for yourself. You are writing for the readers."]
[Exercise: Imagine you are the user.]

A careful assessment of the potential readership of the publication is vital for clear and effective communication. You cannot write effectively for someone without knowing a little bit about them. Better yet, the more you know about them, the easier will be your task of writing for them.

  

[Slide: "Who are we writing for?"]

Let's assess who we've been writing for. Up 'till  now, I think we've been writing for the company. Providing descriptions of product functionality. Page after page after page of what the product does. Boring, methodical listings. Not all that helpful for the poor user who has to wade through every description to find the one they want.

  

[Slide: "Who should we really be writing for?"]

Interesting concept isn't it? Who should we really be writing forremembering that the primary goal is to achieve effective communication? [discuss briefly]

  

[Slide: "The primary goal of writing is to communicate effectively." (again)]

Writing for the user need not conflict with our current concept of writing for the companydocumenting product functionality. Consider this: You are employed by the company to write user documentation. That's what they want you to do. And they want you to do the best you can. Which means they actually do want you to achieve effective communication. You want to achieve itbecause that's your job. And they want you to achieve itbecause that's your job.

  

[Slide: "How do you know if you're achieving effective communication?"]

Are you really achieving effective communication? How do you know? [discuss briefly]

Some measure is clearly needed to determine the effectiveness of our communicationbut that's a discussion for another time. However, before we can measure effectiveness, some focus is needed.  As we concluded in the previous section on document usability, we need to identify the users of our writing, so that we can focus our efforts toward providing them with useful and usable information.

  

[Slide: (progressive) "How can we identify our users? We're: isolated from them, 
provided with what to write, given unrealistic deadlines, given no support." (explanations below)]

You might ask "How can we identify our users? when:

  

[Slide: (progressive) "Q: How can we become user-focussed?"]

Yes, we all understand that manufacturing deadlines cannot be broken, and that we must work within the manufacturing schedule at all times, BUT, that does not mean we can't provide a user-focussed manual or guide for the product within those constraints. 

[Slide: (progressive) "A: With 'User profiles'!"]

The trick is to create and use 'User profiles'; one for each product. User profiles are discussed in detail in the next session.

Back to Top 

[Slide: "Question time (5 minutes);
Toilet/Coffee Break: (15 minutes)"]

Back to Top

1B: User profiles

[Time: 10 mins]
[Slide: "Session 1B: User profiles"]
[Slide: (progressive) "User profiles contain information about the user:
Age range, Nationality, Gender, Education level, Reading style, Patience level,
Product requirements, Documentation requirements." (explained further below)]

'User profiles' are a tool used by marketing and sales people for decades, which they use to help them remain focussed on a particular type of user when they're developing their marketing strategies towards that type of user.

A user profile consists of information about the user relevant to the person using the profile. In this case, us. We would be interested in the type of user who would read what we write. Information like:

  

[Slide: (progressive) Pie-chart representing product user base as a percentage; 
100:0 = 1 user type, 80:20 = 2 user types, 60:40:10 = 2 user types, 30:30:20:20 = 4 user types]

Ideally, the 'user profile' for a product can be represented by the profile of one individual 'typical' user containing all the average user characteristics for the 'typical' users of the product. A user profile consisting of a single user type is suitable where that type of user would represent at least 80% or more of typical users of that product. A separate user type would be required for every group of users that would represent 20% or more of the user base.

A 'user profile' for a product may consist of several individual user types which cannot be amalgamated into one 'typical' user. These separate user types are referred to as "personas". In cases like this however, many 'personas' are used together to form the 'user profile' for the product. A user profile may consist of up to five separate personas.

Back to Top

Personas

[Time: 25 mins]
[Slide: "What is a persona?"]

A persona is a user profile of one 'typical' user for a particular category, like age range, or education level. It would describe the 'typical' details of this type of user for that category.

For example: a persona could be like this: 

[Slide: "Persona 1: Bill"]

William is 35 years old, and resides in the USA. He works in an employment agency as an account manager (recruiter), and earns a reasonable salary. He's technically savvy, having studied computer sciences and human sciences at university. He lives in a mortgaged house in the suburbs of a major city with his wife and children. He's married with one young child (under 3) and with another on the way (due in 3 months). He commutes to work by bus, and reads the daily paper during the journey. He wears glasses for reading small type, but does not require them for his normal daily activities. He's partly colour-blind, but doesn't know it. 

[Slide: "Persona 2: Jill"]

Jillian is 22 years old, and resides in England. She works in an sales office as an accounts receiver, and earns the award wage. She's not very technically savvy or computer literate, having gone no further than high school, although she can use a spreadsheet and email. She rents and shares a terrace house within the outskirts of a medium city. She's single with no children. She commutes to work by train, and reads glossy magazines during the journey. She wears contact lens to correct myopia. 

[Slide: "Persona 3: Mill"]

Millicent is 58 years old, and resides in China. She does not work, having recently retired to care for her grandchildren at home. She's not at all technically savvy or computer literate, having only recently acquired a new computer given to her by her son. She is learning to use email and instant messaging. She shares a residence in a medium city, with her husband, 2 adult children, and their families. Her eyesight if failing and she requires strong glasses to see anything in detail.

  

[Slide: "Multiple personas = User profile";
"Persona 1 AND Persona 2 AND Persona 3 = 'User profile'"]

These are three very different people of different ages, backgrounds and education. They live in different countries on different continents, in very different circumstances. Yet for this example, they all have something in commonthey need to use a BenQ LCD monitor! 

These particular personas are useful to us when we're designing and writing our documentation because these people are so very different. We can use these personas as examples of the range of users of LCD monitors. They might not be exactly 'typical', but they do represent a valid user profile.

  

[Slide: How can we make use of this information?";
"Ask yourself, would 'Bill' understand this?,
Would 'Jill' understand this?, 
Would 'Mill' understand this?"]

Whenever we need to consider if some item in our writing is appropriate or not, we should always refer back to the user profile for the product. Ask yourself if 'Bill' or 'Jill' or 'Mill' (or whoever is the user profile for the product) would understand what you've written, and find it useful, or not. Ask yourself what each of the personas would expect from the product, and what they would be trying to do with the product in their particular circumstance. Ask yourself if what you've written is appropriate for the user in their particular situation.

  

[Slide: How can we make use of this information?";
"Ask yourself, What elements of these personas can we use?"]

What elements of these user personas might be useful for us to consider whilst we're writing a user manual for them?
[discuss (limit 5 mins) use whiteboard if necessary to list ideas]

  

[Slide: User profiles are your best user-focussed writing resource."]

The answers to these questions when posed to the 'user profile' for the product, will determine nearly everything you write for the product. They will answer what is right and what is wrong with your writing. User profiles are your best resource for user-focussed writing.

Back to Top

Summary

[Time: 5 mins]
[Slide: "The primary goal of writing is to communicate effectively." (again)]

We're nearly out of time, so let's sum up. The primary goal of writing is to communicate effectively. That's the important foundation upon which all good writing is built upon.

  

[Slide: "How do we know if we're achieving effective communication?"
"When we become user-focussed."]

Well, given our restricted access to users, and our current work environment, the best we can do for now towards achieving effective communication is by becoming user-focussed. That is, we identify the users of our writing and focus our efforts towards providing them with useful and usable information.

  

[Slide: "How do we become user-focussed?"
By creating and using 'user profiles'!"]

To accurately identify our users, we need to become resourceful. We need to ask our product managers for their 'user profiles'. After all, they're manufacturing a product for a user of some sort aren't they? Surely they have some idea exactly who that user is, or at least what the range of possible users could be? Haven't they done their market research before they built the thing?

  

[Slide: "How do we identify our users?"
"By asking the right questions of those people who should know."]

Even if they haven't done their homework, it doesn't mean we need to remain flat-footed. We can make further enquiries, and piece together our own user profile for the product. That way, we become one step ahead of everyone else who hasn't bothered to do the best they possibly can. We should eventually be conducting proper formal user surveying, however, that's a topic for future discussions.

  

[Slide: "Doing our job to the best of our ability provides us with job satisfaction."]

And isn't that where true job satisfaction comes fromknowing that you have done the best you possibly can?

Back to Top 

[Slide: "Question time (5 minutes)"]

Back to Top

Session 2:
Document structure 

[Slide: "Session 2: Document structure"]
[Handout: Session 2 Notes]

Back to Top

Document structure

[Time: 1520 mins]
[Slide: (progressive) "Types of readers: graphical, comparative, textual." (explanations below)]

There are many factors which effect the way in which users interpret information:

  

[Slide: (progressive) "Ways of reading: skimming, wholly, never, minimal, careful." (explanations below)]

Different people read text in different ways:

  

[Slide: "Writing must remain user-focussed."]

As writers of user documentation, we can't be all things for all people, but we can certainly try to please as many as possible. To do that, we need to know who the users of our documentation are, and what they're trying to achieve. We discussedin the previous writing workshop sessionhow to identify and target our writing to the users of the product we're writing for.

  

[Slide: "Only user-focussed writing can meet user needs."]

So that the users can understand what we've written, the content of our documents must present the information in a manner that is appropriate to the majority of our users. Document structure is the important framework which houses and presents the information that we've written, and binds it all together.

  

[Slide: (progressive) "Publishing conventions: cover, prelims, 
TOC, content, endmatter." (explanations below)]

When designing documents for publication, some well-established conventions and practices used by the publishing industry will predetermine much of the physical document structure. That of:

  

[Slide: (progressive) "Publishing conventions are proven and practical;
However; Don't judge a book by its cover!"]

Readers of books have long come to expect this book-structure and use it natively to navigate through a book, This is a good thing, and should be continued.

However, just because the book itself is fairly rigidly structured, does not mean that the content must be.

We are relatively free to structure the content as we see fit. We can present tables, or graphs, or text, or images in any order and in any way that suits us. There are very few restrictions, other than those we place upon ourselves. The first workshop session on document usability detailed those restrictions. Let's reiterate:

  

[Slide: (progressive) "Useful writing is: written clearly, structured logically, 
ordered sequentially, succinct, easily navigable." (explanations below)]

Our writing must be as useful as possible. It should be:

To achieve this usability, we must write in a way that is understandable to the user, providing information in a logical and sequential order for the user, in just the right amountwithout unnecessary elaborationand in a manner that the user can readily find what they're looking for without frustration.

  

[Slide: (progressive) "Consider the users needs and interests:
What does the user require?; 
What does the user already know?; 
What is the users interest in this matter?;
What is the users attitude?;
What is the users reading style?" (explanations below)]

Only after we've identified and profiled our audience, can we accurately decide on the scope of information they'll require. In more formal writing procedures, these are known as 'user requirements'.

We should always considering the needs and interests of the user. When doing so, we should also:

  

[Slide: "User-focussed writers always use user profiles."]

We keep coming back to this mantra because it's so very important. If I could leave you with just one lesson from this workshop, it would be this: "User-focussed writers always use user profiles." Amen.

Appropriate consideration for the user will help in matching the size, structure and emphasis of the document with the user's needs and interests. For example: these considerations will suggest the amount of background material that should be included, and whether extensive explanations and a glossary might be necessary.

For the graphic artist amongst us, the design style and the number and type of illustrations used should also be greatly influenced by this assessment.

Decisions about vocabulary and tone (which could range from the colloquial to specialist terminology) should also be aligned with the perceived educational and cultural backgrounds of the expected users and their familiarity with the subject.

  

[Slide: "It's now up to you to make it happen."]

How best to structure your documents within this framework is up to you. Be creative; be adventurous and always put the user first. Place yourself in their shoes and structure the document for them. See if it makes our user a satisfied customer.

In the immortal words of Captain Kirk in Startrek: "Make it so!"

  

[Slide: "Quick question time"]

Back to Top

Page layout

[Time: 1015 mins]
[Slide: "Page layout"]

The visual layout of the page plays an important part in the interpretation of the information being presented.

white space

sidebars

headings

navigation

familiarity

  

[Slide: "The primary goal of writing is to communicate effectively."]

You should remember from our previous workshop session where I said that if our writing does not communicate effectively, then we're not doing our job. I said that first and foremost, our writing must be understood. If our readers can't or don't understand what we've written, then we've failed to communicate properly with them. I capped off by stating that it's not their fault, it's ours!

  

[Slide: "Quick question time"]

Back to Top

Page spread

[Time: 1015 mins]
[Slide: "Page spread"]

open book display

right and left side facing pages

balanced visual display

gutters and margins

headers and footers

readability

  

[Slide: "Quick question time"]

Back to Top

Paper sizes and standards

[Time: 1015 mins]

international standard paper sizes

printing from electronic documents

printers offcuts and wastage

fitting within product packaging

  

[Slide: "Quick question time"]

Back to Top

Image capture, format and resolution

[Time: 1015 mins]

Images

Image capturing

Image formats and resolutions

Compatibility

File sizes

Versioning and copyrighting

Back to Top 

[Slide: "Question time (5 minutes)"]

Back to Top

Session 3:
Document template and style usage 

[Slide: "Session 3: Document template and style usage"]
[Handout: Demonstration Session]

Back to Top

Consistency

 

Back to Top 

[Slide: "Question time (5 minutes)"]

Back to Top

Session 4:
Use of English 

[Slide: "Session 4: English usage"]
[Handout: Session 4 Notes]

Introduction

We're about to cover a lot of ground in a very short space of time. I expect that you have previously learnt this subject matter in high school, and understand the terms. If you're not fluent with them, I would like you to take the time to read-up on them after this workshop. I'll just breeze over them here as a quick reminder. You can follow me in the handout notes if you wish.

We're only going to cover the subjects here in a purely introductory manner. If you want to get more details, I refer you these reference books. I can't write knowledgably without them. If you don't know something being discussed, please look it up. I don't expect you to know or remember everything we mention here; but I do expect you to be able to look it up when you need to. 

[Slide: "Reference books: Macquarie Australian English Dictionary, 
Elements of Style, Writing Style Guide, Working Words", Roget's Thesaurus.]

These reference books will help benefit your English writing so that your native English speaking users (mainly westerners) will better understand you. If you don't have these books readily at hand, and constantly refer to them when you're writing the English version of your product documentation, your English writing will suffer, and it will show in your English writing.

Subjects

Back to Top

English grammar (review)

[Time: 2530 mins]
[Slide: (progressive) "Elements of English grammar; article, noun, verb
adjective, adverb, pronoun, conjunction, preposition"]

Grammar is the term used to describe the formation and arrangement of speech; of words and their sounds. In order to be able to discuss grammar terminology, we need to be clear about the different elements of grammar.

As you may recall from English class their definitions are :

Article:
An article is a determiner for a noun which follows it and is the most common word used in English. The definite article is the word 'the', and the indefinite articles are 'a' and 'an'. Indefinite articles are used when the following noun is being used for the first time in the sentence. 'The' implies that the noun is one which the reader has already been acquainted with.
Noun:
A noun is a word that names something: a person, a thing, or an idea. A common noun names things generally like: 'tree', 'house', 'dream', 'man', or 'mouse'. A proper noun names a particular singular person, place or thing like: 'Colin', 'Australia', or 'QANTAS'. A collective noun names a group of people or things like: 'trees', 'houses', 'dreams', 'men', or 'mice'.
Verb:
A verb is a word that describes an action or state, and is normally an essential element in a clause or sentence. A transitive verb describes an action which relates to an object like the way the word 'wrote' relates to the book in 'I wrote a book'. An intransitive verb has no object like the word 'smiled' in 'she smiled'. An active verb is one in which the subject is the person or thing performing the action; whereas a passive verb is one in which the subject undergoes the action. So in the examples above, the 'wrote' in 'I wrote a book' is a passive transitive verb, and the 'smiled' in 'she smiled' is an active intransitive verb.
Adjective
An adjective is a word that describes, defines or evaluates something. An attributive adjective is placed before the noun it qualifies and there can be more than one adjective in that location. For example, the 'pretty' and 'blue' in 'a pretty blue flower'. A predicative adjective is located after the verb it qualifies. For example, the 'good' in 'the prospect looks good'. 
Adverb
An adverb is a word that modifies other words, and is usually located between the subject and its verb. Adjunct adverbs modify a verb (as their name suggests) and specify a time or place of the action, or the manner in which it occurred. For example, the 'nearly' in 'I nearly wrote a book'. Subjunct adverbs modify adjectives and other adverbs. For example, the 'very' in 'a very pretty blue flower'.
Pronoun
A pronoun is a word that refers to a noun or noun phrase that has already been mentioned.
Personal pronouns are: 'he', 'she', 'I, 'we', 'they', 'me', 'you', or 'them'.
Possessive pronouns are: 'his, 'hers', theirs', 'yours', and 'ours'.
Reflexive pronouns are: 'himself', 'herself', 'myself', 'yourself', and 'themselves'.
Demonstrative pronouns are: 'this', 'that', 'these', and 'those.
Indefinite pronouns are: 'each', 'any', 'some', and 'all'.
Interrogative and relative pronouns are: 'who', 'which', 'what', 'whose', and 'whom'. 
Conjunction
A conjunction is a word that is used to connect other words, phrases, clauses and sentences. For example: 'and', 'because', 'but', 'for', 'if', 'or', 'unless', and 'when'.
Preposition
A preposition is a word that links a noun with what was stated beforehand. For example: 'after', 'before', 'in', 'of', 'over', 'to', and 'with'. Prepositions are usually positioned immediately before the noun they are preposing, and many of them indicate place, time, or possession.
[Slide: "Grammar is the term we use to describe English structure."]

However, grammar is not just about the words and what we call them. Grammar is about the underlying practices and conventions by which words combine with each other. 

[Slide: "In English, syntax is the most important factor."]

English is most unlike other languages in its grammar. For example: German, French, Italian, and Roman (Latin) use small inflections and slightly different word forms to indicate meaning and relationship with the other words in the sentence. English, by comparison, relies mostly upon the order of which the words are arranged in the sentencecalled syntax to convey the meaning of the word and its relationship with the other words in the sentence. 

[Slide: (progressive) "In English, some identically spelt words 
perform different grammatical roles in the sentence; 'in the clear' (noun); 
'clear the table' (verb); 'on a clear day' (adjective)."]

Many English words change their grammatical form and meaning without a change in spelling or spoken inflection, dependant entirely upon their position within the sentence and their relationship with the other words in the sentence to determine their actual meaning. For example, the word 'clear' can work as a noun, verb, or adjective: 

[Slide: (progressive) "In English, some identically spelt words have 
different meanings; "Plug-in the extension lead" pronounced 
 leed (noun);
"I will lead you to safety" pronounced leed (verb);
"Lead is a heavy metal" pronounced led (noun)."]

Some English words which are spelt the same have very different meanings and different pronunciation. An example is the word 'lead'. 

[Slide: "English language is constantly evolving."]

Language is not static, and English is no exception. The spoken word evolved long before any method was devised to write it down, and as spoken language is always evolving (with new words being added and unused words being forgotten all the time) the written word can soon become out-of-date. For example: We no longer speak using 'thee' and 'thou' in our sentenceshaving been replaced by the word 'you'although Shakespeare's writing used them very commonly only a few hundred years ago. 

[Slide: "English language is complex and challenging, 
so requires much practise to master."]

English is a complex language and cannot be mastered without years of practice and wide-ranging experience, however, don't let that put you off. Few people ever attain an encyclopaedic knowledge of it, and neither do you. You need only to practice the simple principles commended in this workshop to improve your English writing skills. 

[Slide: "English grammar doesn't have to be remembered by rote."]

One of the most common problems facing writersno matter what you're writingis with the selection of the right words to use. Do you know the difference between affect and effect? Or between alternate and alternative? When should you use an 'a' or a 'an'? Only with practice and constant usage will you be able to remember the correct word usage for any particular circumstance.  But you don't have to remember every obscure word play. There is a better way. 

[Slide: "You just need to know where to look."]

The trick to knowing 'which word to use in which situation', is to know where to look for the answer; and in that, you're not alone. Many people have faced this problem before you, and many solutions have been written in book form for your convenience: 

[Slide: "Reference books are the answer. Dictionaries, Thesauruses, Usage Manuals".]
[Slide: "The smart English writer knows when to seek the wisdom of others."]

When you're not sure which word is best for a particular situation, refer to the wisdom provided in these books. I do, daily. It will make your English writing that much easier to understand.

Back to Top

Sentence structure

[Time: 1015 mins]
[Slide: "Sentence structure."]

For communication to be effective, it requires precise unambiguous expression. Words work best when you not only understand the appropriate context for them, but also know what they really mean, how to spell them correctly, and where to place them in your sentences. 

[Slide: (progressive) "Sentences are built from: words; phrases; and clauses."]

Sentences are built up from words, phrases, and clauses: 

[Slide: "English sentence key elements are:
subject-verb-adjective-object-adverb"]

A sentence usually consists of a noun as the subject and another noun as an object separated by a verb effecting the subject or object. These elements can be further modified by the use of one or more adjectives placed before the object and an adverb placed after the object. The normal order of the key elements of an English sentence is subject - verb - adjective - object - adverb. 

[Slide: "English language relies mostly upon its structure to convey its meaning."]

Each of these key elements can consist of a word or phrase. Because English has so few inflections, the order of the elements is essential to the meaning of the statement. Change the order and you may well change the meaning. Normal sentence order is often reversed in questions, except when the question begins with an interrogative such as 'who' or 'what'. Sometimes, sentence order is deliberately reversed to emphasize a word. For example: 

[Slide: (progressive) "Types of sentences:
simple; compound; complex"]

There are three basic kinds of sentences:

  1. A simple sentence normally contains one clause. For example: 'The train will be here soon.'

  2. A compound sentence contains more than one clause, normally joined by a conjunction. For example: 'The train will be here soon unless it is running late.' Each clause carries equal importance.

  3. A complex sentence contains a main clause and one or more subordinate clauses, such as a conditional or relative clause.  For example: 'The train will be here soon unless it is running late which will make us late too'. 

[Slide: (progressive) "Types of clauses:
principal; conditional; relative; etc."]
[Slide: "A sentence is a group of words who's meaning makes complete sense, 
usually contains a verb, starts with a capital letter, and ends with a full stop."]

Grammatically, a sentence is a group of words who's meaning makes complete sense, usually (but not always) contains a main verb, and when written, begins with a capital letter and ends with a full stop (or equivalent). 

[Slide: (progressive) "Sentences can be written in perspective:
first person; second person; third person."]

The concept of the grammatical 'person' is where the writing is given from a particular (person's) perspective, which dramatically effects the style of writing. This term distinguishes between the person speaking (first person), the one spoken to (second person), and the one spoken about (third person). The differences mostly effect the pronouns:

The choice of first person, especially 'I', has the effect of engaging the reader closely. The use of the first person plural 'we' has the effect of suggesting a solidarity between the writer and the reader. At the other end of the scale, the third person puts distance between the writer and reader, and continuous use of the third person can be very impersonal. 

[Slide: "Sentences can also carry a voice or tone to the reader:
active; passive".]

Sentences can carry an active or passive tone to the reader when those sentences contain verbs which are in active or passive voice. Passive statements tend to tell about what did or could happen, whilst active statements are often directions or instructions for current activities. 

[Slide: (progressive) "Italics in sentences:
names of literature and art; names of publications; names of transports; 
foreign words; word or phrase emphasis."]

The use of italics in sentences have traditionally and principally only used for: 

[Slide: "Pronouns in sentences:
keep the link with the noun clear and obvious."]

When a pronoun refers back to a person or thing previously named, it is important that the gap is not so large that the reader might have difficulty relating the two, and that ambiguity is avoided when more than one person or thing may be referred to. 

[Slide: "Clarity of sentences:
Avoid euphemisms, oxymorons, tautology."]

Avoid euphemisms, oxymorons, and tautology:

Back to Top

Technical jargon and acronyms

[Time: 2 mins]
[Slide: "Avoid the unnecessary use Jargon and acronyms."]

Jargon is a term referring to words or expressions used by a particular profession or group which may not be understood by those outside of that profession or group. Technical jargon are technical words or terms of a technical nature like 'RS-232 protocol'.

An acronym is a word formed from an abbreviation of other words, and is created by taking the first letter of each word it represents. For example 'SCUBA' which is the acronym for 'Self-Contained Underwater Breathing Apparatus', or 'HDD' for 'Hard Disk Drive'.

Unless you are absolutely sure of your user profile, and you know that they are specifically of the same cultural background, ethnicity, occupation, and technical understanding as you or the language you use, you would be wise to avoid technical jargon and acronyms. These tend to translate poorly into other languages, which most likely will have a different point of view, different values, different cultures, and a different understanding of the same technical terms that you may have.

You cannot assume that your readers will have the same education, knowledge, understanding, experience, bias, or viewpoint as you, so you cannot expect then to recognize or understand the acronyms or jargon that you consider normal.

The simple compromise is to avoid the unnecessary use of acronyms and technical jargon in your writing.

Back to Top

Spelling

[Time: 10 mins]
[Slide: "Spelling"]

The spelling of words is a large part of their identity. Small variations in spelling can change a word to another completely different word, so much care and attention should be given to ensuring you always used the correct spelling in your writing. A good English dictionary is the ultimate resource for writers of English, and you should always have one within reach when you're writing English.

The standard spelling for most English words are less than 400 years old. Prior to that, English documents were written in regional dialects with great variation in spelling, even within documents. It wasn't until the advent of word lists and subsequently dictionaries that English spelling became standardized for most words. Nowadays, about 98% of words in common use are not subject to variation.

Differences between British and American spelling can cause some grief if you're not familiar with the history. Basically, British spelling is derived from Johnson's dictionary of 1755, and American spelling is from Webster's dictionaries of 1828 and 1838. Overall, American spelling is more standardized than that of British spelling, though it is not without its own anomalies. The major differences lie in the spelling of  'ae', 'i/y', '-ise/-ize', '-l/-ll-', 'oe', '-or/-our', and '-re/-er'. Australia stands somewhere between the two and recognizes both forms of spelling.

British American Example
-eable -able useable or usable
ae e encyclopaedia or encyclopedia
-eing -ing ageing or aging
-ise -ize recognise or recognize
-l -ll instal or install
-ement -ment judgement or judgment
-oe -e homoeopath or homeopath
-ogue -og dialogue or dialog
-our -or colour or color
-yse -yze analyse or analyze

Frequently misspelled words [handout]

Frequently confused words [handout]

Commonly confused pairs of words [handout]

Back to Top

Capitalisation

[Time: 2 mins]
[Slide: "Capitalisation"]

Capitalisation of sentences has traditionally been done for headings, titles, and captions.

Capitalisation of words within sentences has traditionally been done for place names like suburbs or train stations, and for added emphasis.

Capitalisation of the leading words into sentences is traditionally done for display presentation purposes.

The start of all English sentences are usually spelled with an initial capital letter. The only exceptions are where part quotes of conversations are being retold, and where sentence structure is convoluted by the use of compound sentences and punctuation marks. That is, the parts of sentences following colons or semicolons are usually not initial capitalized.

All proper nouns and acronyms are normally spelled with an initial capital letter, even if they do not occur at the start of a sentence.

Today, words are rarely capitalized within sentences, unless announcing place names or acronyms. The use of capitals in headings and text is a leftover from the days of typewriters, which did not have the ability to change font sizes, italise or make text bolded.

The use of italisation and bolding is now preferred over capitalisation to provide appropriate emphasis. 

Back to Top

Punctuation

[Time: 15 mins]
[Slide: "Punctuation"]

Full stop

Comma

Semicolon

Colon

Brackets

Dashes

Question mark

Exclamation mark

Quotation marks

Apostrophe

Hyphenation

 

Back to Top

Tense

[Time: 5 mins]
[Slide: "Tense"]

English uses variations in its verb forms to indicate whether an event is in the past, present or future. For example:

The use of the present tense serves to involve readers in the statement and to lend it vividness. Use of the past tense tends to detach the reader from what's being stated.

Future tense is created by compound verbs involving auxiliary words like 'will', 'shall', 'am', 'is' or 'are'. For example:

Compound or complex sentences run the risk of different tenses between their clauses. Most often the tense of a verb in a subordinate clause is influenced by that of the verb in the main clause. For example, when the verb of the main clause is present tense, the subordinate verb is likely to be the same. You should be careful to avoid conflicting tenses in your writing.

In English, the past tense of a verb is denoted by an inflection of the end of the word. Usually, the letters '-ed' are appended as in the case where 'installed' is the past tense of 'install', and where 'press' becomes 'pressed'.

Note that where the verb already ends in an 'e', the 'e' is dropped when the inflection '-ed' is added, to prevent a double 'e' sound. For example, 'handle' becomes 'handled', not 'handleed', and 'operate' becomes 'operated'.

Some verbs use the alternative past tense ending '-t'. The last few letters are altered to '-t', as in the case where the past tense of 'build' is 'built', or where 'kneel' becomes 'knelt'.

For most verbs, their endings are fixed and a dictionary can provide their correct spelling. However, a small list can use either the '-ed' or '-t' endings equally. For example:

More often than not, the use of the '-t' variant ending for this list is where the word is being used in an adjectival manner. For example, compare these sentences:

A participle is a word formed from a verb and used as an adjective or noun. In the example above, 'burnt' is a verb in the role of an adjective. Participles are commonly referred to as being in the present or past tense. Present participles always end in '-ing', and past participles end in '-ed', '-en', '-n' or '-t'. For example, the word 'going' is present tense, and 'gone' is past tense; 'being' is present, and 'been' is past; 'burning' is present, 'burnt' is past.

Participles contribute to the active/passive distinction of the tone or voice of a sentence, in that the present participle is always active voice, and the past participle is normally passive voice. 

Back to Top

Logical structure

[Time: 5 mins]
[Slide: "Logical structure"]

Documents should be structured in a transparently logical manner to the user, so that they can locate the information they're after as easily as possible. The user needs to clearly see how the document is structured so they can decide where to go. Like a map. This is most readily achieved through just that, a graphical map. A plan of the document's structure, laid out for all to see. The skeleton exposed showing how everything connects together. Like a table of contents, but graphicalnot textual.

Providing the user with what they want in a way that they can readily find it, is the ultimate goal of the user-focussed writer.

The document could be:

Which of the above orders do you think will assist the user most of all? [discuss briefly].

Whatever structure you choose for your documents, there should be a compelling reason for it. And it should be logical to the user or they may not use it.

Back to Top

Gerunds in headings, TOCs and indexes

[Time: 5 mins]
[Slide: "Gerunds"]

A gerund is the common term for the present participle of a verb ending with '-ing' and performing as a noun. It's grammatically referred to as a verbal noun. For example: 'smoking' in 'Smoking kills!'.

When writing user-focussed documentation, because the user is more often than not trying to do something, the use of the gerund is an extremely user-friendly way of helping the user find what they're looking for. Particularly when the user is looking for information in the headings, table of contents, and index, where your gerunds should be located.

For example:

The words 'installing' and 'connecting" should be used in the heading, in the table of contents, and in the index rather than their verb forms 'install' or 'connect'.

Back to Top

Metaphors and similes

[Time: 5 mins]
[Slide: "Metaphors and Similes"]

Metaphors are a 'figure of speech' consisting of a word or phrase used to describe or represent something to which it is not literally applicable. For example, when describing a golf shot to be 'rocketing its way to the green', the metaphorical 'rocketing' brings lively imagery to the sentence. Metaphors are said to be the life-force of language, as they bring vitality to routine commentary on any subject. Metaphors can often be used to demonstrate the writers wit, and are commonly overused by sports commentators.

Mixed metaphors are created by using two or more divergent metaphors in quick succession, and tend to confuse rather than clarify. For example: 'He has his head so deep in the sand that he doesn't know which side of the fence he's on.' Metaphors, like most stimuli, need to be used in moderationnot too oftenand not exploited too much. An extended metaphor can work well provided it's not over used. Bringing a closing comment back around to an opening metaphorextending the metaphoris a technique often used by debaters and speech writers.

Similes are also a 'figure of speech' consisting of a word or phrase, however instead of describing something as a metaphor does, similes compare something directly with another thing of a different kind to add meaning. For example, when something is said to be 'as solid as a rock', or 'as black as coal'.

In a simile, the comparison is made by a phrase beginning with the word 'like' or 'as', and the image it raises is placed alongside the statement (for direct comparison) rather than integrated with it as with a metaphor. Similes are far more direct and explicit. Similes allow for more complex comparisons which cannot be made by a single word. 

[Slide: "Synonyms and Antonyms"]

Synonyms are words that are identical or close in meaning to each other, such as 'close' and 'shut'. Synonyms are a useful way for writers to vary their expressions, and the ultimate collection of synonyms is a thesaurus.

Antonyms are words that are opposite in meaning, such as 'alive' and 'dead'. A thesaurus lists antonyms as well as synonyms and should also be kept within reach when you're writing English. A well indexed thesaurus is a powerful resource for good writers.

Back to Top 

[Slide: "Question time (5 minutes)"]

Back to Top

Session 5:
Document control and management 

[Slide: "Session 5: Document control and management"]
[Handout: Discussion Session

Back to Top

Tools

[Time: xx mins]

 

Back to Top 

[Slide: "Question time (5 minutes)"]
Back to Top

See Also

Jump to site index page Lotech Solutions' Tips, Tricks, and Procedures

For global distance between cities, see Jump across to a separate website on the internet http://www.wcrl.ars.usda.gov/cec/java/lat-long.htm

Back to Top