Technical Editors' Eyrie Newsletter

Issue 69, 16 February 2003

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com

In this issue...

Internationalisation, localisation, and translation
British, Canadian and American English
American - Australian vocabulary
Another resource on simplified English
Steve Hudson on internationalisation of documentation
Reviewers needed for my new book
Style guides for training materials: follow-up
Subscription information

This issue contains some correspondence. Please note that I do not publish correspondents' names or addresses without their permission. If you do write, and you don't want your letter published, even anonymously, then say so in the note.

Back to top


Internationalisation, localisation, and translation

Internationalisation: writing for an international audience that includes native speakers of another variation of English and people with English as a second language. In this case you want to be as culture-neutral as possible, and be aware of the needs of some ESL readers.

Localisation: writing specifically for readers in another country or culture, particularly when you need to include culture-specific information such as currency or taxation issues. Accounting programs such as Quicken usually produce localised user guides; some programs provide a country-specific addendum to a generic user guide. The written product is in English.

Translation: the English material will be translated into one or more other languages. Material that has been well-written in English for either internationalisation or localisation is often cheaper to translate because the translator doesn't have to deal with as many cultural as well as vocabulary changes.

Obviously there is quite a bit of overlap between these categories, but they are not quite the same thing. Editors need to know which type of writing is intended in a given project, because their changes and recommendations may vary.

This newsletter includes several articles related to these issues.

Back to top


British, Canadian and American English

Numerous editors have been lamenting the fact that spelling checkers (such as the one in recent versions of Microsoft Word) don't provide any easy way to specify the preferred spelling of words ending in '-ise'; both '-ise' and '-ize' are accepted as correct in the Oxford Dictionary and other authoritative sources, but house style normally dictates one or the other. Some people would like a word list to use as a starting point for building an exclude dictionary to assist in finding the "wrong" variation.

In the course of one such discussion, I commented: "Actually there are more differences in the varieties of English than just spelling, and some of them are rather more important than the spelling. Probably not many of those differences will be significant in software user docs, as long as the writers avoid various colloquialisms, sports metaphors, and some other things that may require a cultural knowledge that the target audience doesn't share. Most Brits, Aussies and others are used to reading software docs written in American, so they'll probably get along just fine.

"However, I know from experience that some terms are unfamiliar to readers "across the water" and cause them to stop and wonder if they really understand what's going on. So if you have the budget, get a native (or at least highly experienced) speaker of the "other" English to go over your docs and spot any problems of that nature. That would not be the same as a translation and wouldn't take as long or cost as much.

"BTW, not all those spelling changes would be handled easily by a tool. You certainly wouldn't want to change all instances of 'check' (money term) to 'cheque' because of the frequent use of 'check' for other purposes in software docs ('check to see if xxx' or 'place a check in the box')."

Keith Soltys Keith.Soltys@tsx.com writes to recommend Karen's Linguistics Issues at http://www3.bc.sympatico.ca/linguisticsissues/

"On the Lexis page, http://www3.telus.net/linguisticsissues/LexisContents.htm you'll find:

Back to top


American - Australian vocabulary

Recently an Australian editor was looking for a list of words and phrases to look out for when editing a book for an American audience. I found this website, which doesn't claim to be complete (and is for a general, not technical audience), but it might help: http://www.statsci.org/smyth/ozus.html

I think an editor could work out a lot of terms from a UK-US English comparison list. Here's a fairly good one: http://www.aussieslang.com/directory/uk-us.asp

Of course, nothing beats having a native American speaker go over the text. I'm a bit out of touch with modern American colloquialisms (having lived in Australia now for 28 years), but I still catch things -- such as brand names -- that slip by some Australian writers.

Back to top


Another resource on simplified English

Gail Warman writes:

"You may be interested to check out the website for Russ Brown's UserLab Inc, which includes some useful materials on simplified English. http://www.userlab.com/SE.html "

Back to top


Steve Hudson on internationalisation of documentation

Steve Hudson cruddy@optushome.com.au offers some hints for editing material for an international audience.

"Some simple techniques:

  1. Avoid idioms. These are more pervasive than you realise.
  2. Use present tense, active voice.
  3. Reduce sentence size.
  4. Know your declensions and minimise them -- usually through sentence fragmentation.
  5. Examine active vocabulary (I have some basic free tools to help with this) and simplify. The easiest way to do this is to look at the list of least frequently used words and examine for synonyms.
  6. Follow all good writing techniques - a few of which are not used in this example. (E.g., avoid parenthetical phrases.)
  7. Toning-down English? You are almost on the right track. Here's a simple example. I wanted to explain an Octagon. The original text used a traffic Stop sign. Here in Australia, and indeed a percentage of the western world, it's an octagon. However, many countries use a round stop sign."

Back to top


Reviewers needed for my new book

I am writing a short (approx. 150 pages) book titled "Taming OpenOffice.org Writer" and I need some technical writers or editors to usability test it for me. The book is aimed at intermediate and advanced word processing users who have the sort of requirements that techwriters have: rigorous use of styles and templates, lots of figures and tables, multi-chapter documents, conditional text, copious cross-references, and so on. The book assumes the reader understands the basics (how to open and save documents, enter and edit text, that sort of stuff), which are similar to MSWord, FrameMaker, and many other programs.

OpenOffice.org is an open source program that runs on Windows, Linux, and some other platforms. The latest stable release is 1.0.2. It's a 50+MB download; modem users can get a CD for trivial cost from a variety of places. Check this page for vendors of CDs: http://distribution.openoffice.org/cdrom/

If you're interested in trying out OpenOffice.org and would like to review my book, please contact me for details. I am not looking for copy-editors at this point; I am looking for people to (a) see if the instructions make sense and work; (b) tell me if I've left out any topics they think should be covered; and (c) make other substantive comments.

I cannot pay reviewers, other than sending you a copy of the printed book when it is published and acknowledging your contribution (unless you want to remain anonymous).

The OpenOffice.org website is here: http://www.openoffice.org/

I have some pages about OpenOffice.org Writer, starting at http://www.jeanweber.com/howto/openoffice.htm

Back to top


Style guides for training materials: follow-up

Last issue, a reader requested suggestions of websites or other resources about style guides training materisls. Several people wrote to offer assistance. Here are two responses.

Steve Hudson, cruddy@optushome.com.au:

"1) Training materials
All training manuals need extra white space to write in. I usually compensate by printing training materials SIMPLEX so that the reflex / obverse side is blank for said scribble, with double-sized margins.
 
"2) Training the trainer
Essentially this tells how to conduct the training session. It highlights important notes and FAQs. It describes all facets of the student materials. It provides anything from a skeleton to a fully blown word-for-word presentation.
 
"It includes materials that are presented to students by the trainer, and for each workbook exercise for the students it provides a detailed look at the expected results and knowledge transferred. It should also highlight potential problem areas in this exercise.
 
"3) Illustrating your work
A personal opinion. This is all IMHO. Every illustration should add meaning to its accompanying text. If it doesn't, it's wasted space. Thus the "Dummies" books are excessively illustrated. Why? Their target audience. They aren't tecko, they are scared and confused; humour goes a long long way to improving these. For users who are forced to use your doco on a regular basis, these illustrations end up cluttering the work and make it harder to extract the required information.
 
"Thus, if it's a reference manual that's expected to be pulled out time and time again, only use appropriate illustrations. If it's a workbook for a single one-off class - heck, draw me a five- legged Martian discussing the pros and cons of a step ladder for all I care. This can lead to 'stark,functional' trainer books - which quite frankly is spot on. The trainer has to do it for a living, the audience doesn't. We have to woo the audience, but merely educate the trainer. The trainers' books are dull, the students' books are funny etc."

Renee Atkinson r-trainer@bigfoot.com:
"I create workbooks for a corporate trainer... I am constantly searching on-line, at book stores, magazine racks, etc. for ideas. We use lots of graphics in our workbooks. I even did an entire workbook in Comic Sans because it was on dealing with difficult people, and we felt the 'fun' font would take away some of the sting of what the trainer had to say. I'd be happy to send samples of some of my creations and if anyone else would like to share what they've done, I'd love to see others' works.

"One book I do use and love (and keep waiting for the 2nd edition to come out) is Terrific Training Materials: High Impact Graphic Designs for Workbooks, Handouts, Instructor Guides, and Job Aids by Darlene Frank.

"Just some additional (rambling) thoughts: I try to use an interesting heading style, such as 18pt. Arial, in a black box, reversed type. Or have lines under the headings. Any time I create a list, such as '8 Ways to Tell that Difficult Person to Lighten Up' (and yes, some of my client's headings are just that long!) I would use Word Art to create the number 8.

Another reader contributed,
"I have seen many examples of workbooks. None of them had an 'academic' look.

"I have written several train-the-trainer guides which were met with total enthusiasm by the client. In most cases my work was aimed at military or government workers.

"I used small 'graphics' which I made from the usual fonts offered in Word (wingdings, etc.). By enlarging a symbol, you can make it look like a graphic. The clients liked check boxes, check lists, tips, tools, reminders, notes sections, 'case study' stuff that reflected their work and the instructor can use as discussion points.

"Do not overwhelm with graphics. It is mostly a matter of attention to the 'visuals' that relieve pages of text. Clients are not usually willing to pay for 'extra' graphics so be creative. I don't like the cartoon look either but you can create your own look--I would not use university textbooks as a model for the audiences I work with. Explain to the client that if they are going to keep up the manuals on their own they will have these 'graphics' available themselves in Word.

"My t-t-t manual included possible room set-ups, exhaustive supply checklists, good teaching techniques, how to handle difficult students, introductory ice breakers, evaluation checklists, suggested questions that reflected the major points in case studies [never leave the instructor hanging--always give them more than they need], tips on how to do the flip charts in advance, traits of adult learners, etc. The train-the-trainer material was separate from the teacher's guide, which was a step-by-step manual that walked through the training mirroring the student manual.

"When I started writing training materials, I thought the clip art I pasted on the final copy was not very professional looking. However, the client loved it. We have given up clip art, scissors, and paste but I think you can find a lot of free graphics on the internet.

"You might want to check out the National Society for Performance and Instruction website for material on train-the- trainer. I also see workbooks and self-instruction guides at the local library that are aimed to teach adult learners how to do something."


<Advertisements>

My books: Taming Microsoft Word and others

Taming Microsoft Word (3 editions, for Word 2002, 2000, and 97) http://www.jeanweber.com/books/tmw
Editing Online Help http://www.jeanweber.com/books/olhbk.htm
Electronic Editing http://www.jeanweber.com/books/e-edit.htm

More sales, less work with AWeber

Automated e-mail follow-up from AWeber. Includes an email list, autoresponders, ad tracking, and real-time statistics. I use this system to send out copies of this newsletter. Click here to find out more.

Diversify your business and increase your income

Your time is limited, and so is the amount you can charge for your time. Learn how you can increase your income by diversifying.

</Advertisements>


© Copyright 2003, Jean Hollis Weber. All rights reserved.

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is available as emailed ASCII text.

To subscribe, use signup box on any page of this website.

To unsubscribe, see instructions at the end of each newsletter you receive.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.