Category: Communication

May 2, 2013

Let’s chat about terminology and best practices

Our latest monthly chat was on a topic at the core of technical communication: terminology. Fourteen of us working in technical communication and translation got together by phone/web chat to share our thoughts and experiences on this topic and hear how we were all managing our terminology.

Terminology isn’t just for localisation

Unfortunately when some companies hear the word “terminology”, they simply think “localisation” – terminology management is a part of the translation process. But it actually kicks in right at the beginning of product development. If you don’t watch your source language terms (for most of us that’s English), then you risk messing up your translated terms too, impacting quality, cost, and time to market of your products across all languages.

Most of us in the chat had between 500 and 5000 English terms documented, usually kept in Microsoft Excel. Some used a permission-based wiki to manage their company’s source language terminology as it is ideal for sharing and collecting information in a central repository. A participant remarked that terminology management systems (TMS), which are used to store and retrieve terminology information, can be difficult to implement.

Yet many of us have problems keeping terminology consistent and correct across all our required languages. And a frequent reason was multiple groups across a company creating their own terms, such as software developers.

Best practice: Collect and control terminology early in a product development cycle.

Who “owns” the terminology?

We agreed that the terminology management process and reaching consensus were more important for ensuring consistent and correct terminology than which tool is used to manage the terms.

Practically none of us had access to a terminologist. The terminology work usually falls upon the technical writers and translators. Yet a common problem faced by several in the group was not being included in the team designing the user interface and advising on the terms to be used. One translator in the call has been asked by a client to propose English terms for them to use in their software.

A couple of us were in the fortunate, and enviable, position where the Technical Publications department is responsible for their all company’s English terminology. In one company the developers can’t use a term in the user interface unless it has been approved by Technical Publications. Sadly this is not usual in most companies.

Best practice: Have a terminology team that selects, defines, and approves the terms.

Controlling the English

Unfortunately for many of us dealing with inconsistent or poorly defined terminology is a regular problem.

One solution proposed in the chat is to use simplified English. One participant uses an open-source (and free) term checker for ASD Simplified Technical English, which is fully customisable. Go to simplified-english.co.uk for more information on this tool.

Mergers and acquisitions (M&A) had a mixed impact on terminology. Sometimes companies let acquired/merged groups keep their different terminologies as often their products stay separate. However, when products are integrated following an M&A, reaching consensus on terminology can often become political. Managing terms then becomes particularly complicated.

Best practice: Use consistent and correct terminology that has been approved by the company.

Importance of structuring terminology

The translators in the group regularly have to work with terms that are poorly defined so it’s often difficult for them to know the context and figure out how to translate the terms.

We need to provide more information about a term than simply its definition. If you only provide a list of English terms and their translations without definitions or context, then over time the quality of the software and documentation translations will decrease. Unfortunately we didn’t have time to discuss how we collect our terms.

Every term should at least have a definition, subject field, context, part of speech (noun, verb, adjective, or adverb), and abbreviation/acronym (if relevant). Depending on how many products and channels there are, you could also classify the terms by product/channel group. It’s also worth thinking about including the associated deprecated terms so that everyone knows not to use them.

Best practice: Document each term with appropriate metadata.

Find out more on managing terminology

An excellent document how to manage terminology is: Terminology for Large Organizations (link opens PDF).

Results of a survey done in 2010 on terminology practices in the localisation & translation industry: TTC Survey 2010 (link opens PDF).

April 17, 2013

Why we need to know about EU Directives

by Kelly Parks, Membership Manager

Let’s say you were creating documentation for consumers in a European Union (EU) state. You have a plethora of issues to consider: adequate research, the consumer’s language, translation costs…the list goes on. However, laws can vary depending on which EU state the product will be sold in. The EU Commission created Directives in an effort to harmonize these laws and make it easier to do business across the member states.

What are European directives and how are they different from European regulations?

The purpose of directives is to harmonise the laws of different member states of the EU. These directives set out goals that all EU countries must achieve. However, each country is allowed to decide how they reach those goals. “National authorities have to adapt their laws to meet these goals,” says Europa.eu, “But are free to decide how to do so.” There are directives for almost any topic, including:

Healthcare, medical devices, and pharmaceuticals
Environment and the conservation of animals and habitats
Copyrights and trademarks

Regulations, however, are far stricter. They are cold, hard rules. Europa.eu describes regulations as “…the most direct form of EU law – as soon as they are passed, they have binding legal force throughout every [EU] Member State, on a par with national laws. National governments do not have to take action themselves to implement EU regulations.”

Do European directives affect technical documentation?

Absolutely. Take the Waste Electrical and Electrical Equipment (WEEE) directive as an example. As part of the WEEE directive, the WEEE symbol
(shown below) must be visible on applicable electrical products. This symbol means that the product does not belong in public waste. If you are writing the user documentation for such a product, you are responsible for ensuring that:

This symbol is defined on user documents.
Information is provided as to where the product can be disposed of.
The potential environmental impacts of disposing this item in public waste are clearly communicated.

For more information on the WEEE Directive, visit the EU legislation summary page on waste electrical and electronic equipment.

To complicate matters, directives (and regulations) are written in legal verbiage that can cause glossy-eye syndrome. The legal verbiage makes it hard for technical communicators to understand the directives and how to address them in their documentation. Therefore, it’s important that technical communicators work closely with their regulatory or legal manager.

Each directive document presents a large amount of information that needs to be sifted through. However, it is time well spent because the consequences of not following the directives are worth avoiding. If the user documentation does not meet the goals set out in the directives, the product cannot be sold in the EU – which puts the technical communicator in a rather rough spot.

What has been your experience in working with directives? Share in the comments section.

December 4, 2012

The functionally illiterate tourist and travel guides

by Jen O Neill

We hear about the growing problem of functional illiteracy. However, for many of us in technical communication, it may not be an issue that we consider when we write for our target audiences. Yet if our work is read by users whose native language is not English, then we well need to consider the needs those readers who have poor English.

What’s it like to be an adult who can’t understand the text in front of them? How much more complicated does it become when you can’t speak the local language but must still find and communicate information?

I visited Moscow and St Petersburg for the first time in October, 2012. I can’t remember why, but I bought a different travel guide for each city. I got the Lonely Planet guide for Moscow (2012 edition) and the DK Eyewitness Travel guide for St Petersburg (2010 edition). Most of my time in Russia was spent in St Petersburg.

Two very different cities when it comes to communication

Over 2.5 million foreigners visit St Petersburg and 4 million visit Moscow annually. St Petersburg is more sympathetic towards its foreign visitors than Moscow. Unlike Moscow where everything is written in Cyrillic only, downtown St Petersburg has “bi-lingual” signage. The signage, such as street and metro names, includes both the Cyrillic script and its transliteration in Roman script.

Information looks very different in Cyrillic, even when referring to familiar things like the MacDonald’s fast food restaurant. Names that are familiar at home become incomprehensible. Cyrillic only shares a few common letters with the Latin script that we use in Western European languages.

I don’t know Russian. I didn’t have time before to learn the Cyrillic script before I left on holiday. So this meant that I was effectively functionally illiterate during my stay in Russia. I also would be unable to talk with people unless they understood my (foreign) language.

But everyone speaks English, right, or at least the younger generation does?

Few Russians speak English. Nearly everyone I stopped to ask for help in both Moscow and St Petersburg had little or no English regardless of their age. This meant that I was dependent on my guide books for much of the information that I needed.

To help their readers, both travel guides had a section with many commonly used words and phrases, such as “Please”, “Thank you”, “Excuse me” and “Hello”. Both show how to pronounce the words and phrases. I found that the DK Eyewitness Travel guide had a more extensive list of words and phrases. However, they were written in smaller type than those in the Lonely Planet guide.

As a functional illiterate who couldn’t speak Russian, I wasn’t keen on trying out sentences but appreciated having the simple everyday words to use. To stop a stranger in the street and try to pronounce a couple of phonetic phrases from a guide book before the person walks away can be challenging, “Gdye Khram Spasa-na-Krovi ? pa·ka·zhih·tye mnye pa·zhal·sta (na kar·tye)” [Where is Church on Spilled Blood? Can you show me (on the map)?]

What was I supposed to do when the answer comes back in Russian, which I don’t understand?

I found it easier to keep to the simple “Please/Thank you” Russian words and point at the Cyrillic text or photo in the guide book or metro map and gesture, “Where is?” or “Am I here?”

This meant that I needed a guide book that let me “speak” with my finger.

I would need to be able to point at some specific information in the guide. The locals would need to be able to quickly understand my problem, although I’d have an answer in a language I wouldn’t understand. So I needed a communication system that was visual.

Let your fingers do the talking

The two travel guides are designed differently. DK Eyewitness Travel has a very visual layout with colour-coded chapters on each city area to visit and many photographs. Lonely Planet has minimal colour (mainly black text with blue headings) and some colour photographs. Both have a local map in each chapter on an area being described as well as a detailed main street maps at the back of the guide. As expected, both also have chapters with practical information on such subjects as transport, language, top tourist itineraries, restaurants and entertainment.

The DK Eyewitness Travel guide was much more encouraging for “talking with your finger”. Its visual layout made it much easier to point at specific information when showing a page to someone. The Lonely Planet layout was not designed to have its information shown to someone.

Here’s an example of an entry in the Lonely Planet guide for Moscow (click to enlarge):

Here’s an example of an entry in the DK Eyewitness Travel guide for St Petersburg (click to enlarge):

Examples of local area maps in the two travel guides (click to enlarge):

The DK Eyewitness Travel method of clearly categorising information on a site to visit became particularly important once I travelled outside of the city centre to the suburbs—when the signage is written in Cyrillic only. But it was still easy to point at the photo or the Cyrillic name of the place I wanted to visit and then point at, say, the bus number listed to “ask” people where on the street the bus stop is located for this destination. Everybody quickly understood what I needed to know and replied in gestures too.

I still haven’t seen the Lonely Planet’s guide for St Petersburg but if the information design of Moscow guide is anything to go by, I can’t image having this “finger dialogue” with strangers using their guide.

It really helped having a picture of the site I wanted to visit when asking for directions by gesture. During my stay I must have stopped dozens of people and ask them for information simply by pointing at items in my travel guide and making gestures such as “Where is?” I was often amazed (and relieved) that although I had no common spoken language with the Russians, we somehow had a common language of gestures, and everybody was always helpful.

Numbers. The universal language

I may not have been able to speak Russian but besides having the travel guide to help me, I had another tool that proved invaluable when I needed to converse with locals—the mobile phone.

I was on a limited budget so ate in lower priced canteens and buffet-style restaurants. When I’d reach the cash desk to pay, the cashiers would realise that I didn’t understand them and they would type the price on their mobile phones and show me the number. The phone was also great when haggling in markets. The vendor and I would simply enter the price on our phones that we were each expecting to pay or charge and show each other the number. No speaking; just shaking or nodding of heads and a phone to display the price. Simple yet effective.

A travel guide on Moscow without a metro map and no station names written in Cyrillic?

The easiest way to get around Moscow is by metro. Moscow has a large metro system with over 180 stations, many of which are architecturally beautiful. However, the metro system only shows the station names in Cyrillic characters.

There are metro maps shown on walls throughout the stations. Unlike Paris, for example, Moscow doesn’t hand out free printed metro maps to users to help them around a complex system. Although you can get a map of the Moscow metro on the web (in Flash) that shows the station names in both Cyrillic and Roman characters, the Roman-character names are in grey and are difficult, if not impossible, to read. Did the Lonely Planet travel guide consider this issue?

Frustratingly the Lonely Planet guide doesn’t include a metro map. To make matters worse, it only gives the Roman-character names of metro stations in its texts. So this can make using the metro system difficult if you don’t know the Cyrillic alphabet.

Up to nine million people use the system daily. So it’s often –very– crowded, which can make it difficult to read a station name on platform walls when you’re in a metro carriage. If you only have the Roman character name to use from your guide book, then it becomes more difficult to quickly figure out where you are on a metro line. You need a map if only to be able to count the number of stations you must travel before getting off or changing lines.

The DK Eyewitness Travel guide of St Petersburg includes a metro map. This city’s metro system is smaller than that of Moscow’s with only 65 stations. All stations have bi-lingual signage (Cyrillic/Roman scripts). Being a smaller system it’s easier to include a metro map in the guide. Although Lonely Planet includes a separate fold-out map of Moscow streets, there’s none for the metro included. This is an extraordinary oversight for such a fundamental tool to help tourists.

The Moscow metro service could also improve their map on their web site to make it more readable.

The problem with signage

As a Western European I’m used to seeing text-free icons in signage to tell me where things are located in buildings or on the street such as toilets, exits, left luggage, or taxis for example. However, Russia uses few, if any, text-free icons in its signage to communicate information. Moscow in particular is very text centric. If you can’t read Cyrillic script then the city isn’t going to help you. This means that you can’t read the signage in a railway station, for example, if you don’t know the language.

Unfortunately the list of words and phrases provided in both guides doesn’t consider this signage issue. They don’t include many common standard signage terms such as “Left luggage” or the words used in a train arrival/departure timetable such as “Platform”.

I planned to see St. Basil’s cathedral in the Red Square but first had go to the train station to leave my suitcase where I was to catch the night train to St. Petersburg later that day. I knew you could leave your suitcase at the station but I didn’t know the Russian term for “Left Luggage”. I couldn’t read the signage. Neither guide book listed the term and no one I asked in the station spoke English. They understood the word “Baggage” but I couldn’t understand their answers. I never found the Left Luggage section in the large railway station. I can’t believe that I went all the way to Moscow only to stand outside the cathedral because I didn’t know the word for “Left Luggage”. I couldn’t enter the cathedral with a suitcase. Both travel guides gave lots of terms for reading menus (which I didn’t need as I went to lower cost places where I could point at the food on offer) but little on realities of using buildings such as railway stations.

In 2014 Russia hosts the winter Olympics in Sochi in the Caucasus mountain. There will be a significant increase in the number of foreigners passing through Moscow on their way to the games. Most will be functionally illiterate in Russian like me. Will Moscow improve its signage to make it easier for us “illiterates” to get about in the city? I didn’t see much evidence during my stay. Will travel guides start to consider signage issues?

Why still use a paper travel guide?

The printed map of the Moscow metro that I had downloaded was poor quality and difficult to read. I have a smart phone so why didn’t I just download some apps to my phone to help me get around the metro and streets of the cities? There are some excellent ones available, even for free.

Roaming charges. Unless you’re not bothered about going broke with roaming charges or you’re using a company phone (so you’re not picking up the tab), you can quickly run up a significant bill from roaming charges when travelling overseas. As I wanted to regularly phone a friend in Siberia during my stay in Russia and I was on a limited budget, I bought a Russian pay-as-you-go SIM card at a railway station to control my phone costs. So I had no access to potentially helpful apps or such tools as Google Maps.

Paper maps and guides aren’t going to disappear any day soon. Paper doesn’t need an internet connection and is available 24/7 with no running charges.

Which guide book did I prefer? Lonely Planet or DK Eyewitness Travel?

I was in Russia for less than a week so had lots to see in a short time. I couldn’t read or speak the language and was travelling by myself on a limited budget. I wanted to explore.

Although I haven’t compared the two travel guides for the same cities, their respective designs are the same for all the places they cover. Lonely Planet probably contained information on more sites to see that DK Eyewitness Travel guide but the layout was cramped. It was often almost identical looking pages of dense type with blue headings. The Lonely Planet world is largely monotone and text orientated.

As a functionally illiterate tourist, I really appreciated having information that was communicated visually.

DK Eyewitness Travel won hands down with all its pictures and easy to use colour-coded chapters. I could quickly find my way around the guide. Its maps were much easier to read than those of Lonely Planet. It got me out there, actively exploring, interacting with the locals. Even if we didn’t share a common language, I was able to “dialogue” with them when I needed help.

But it isn’t just the content that matters. The book design does too. The DK Eyewitness Travel guide has a binding that let the pages stay open when you placed the guide on a table (so you could continue to read it while eating, for example). Lonely Planet slams shut; it always has to be held open or placed open facing down on a surface.

The binding of the DK Eyewitness Travel guide lets you open it back on itself without damaging the spine. Very useful as I usually had it stuffed in my bag, folded open on the page showing the metro map for quick access. DK also has useful robust flaps on the front and back covers to be used as bookmarks so you could quickly locate sections important for that day’s exploration. Could just be my eyesight but I found that there was a better contrast between the black text and white page in the DK Eyewitness Travel than the Lonely Planet. I wasn’t always reading in perfect lighting.

The DK Eyewitness Travel guide has been designed to encourage use and interaction, not just passive reading.

What should you look for in a tourist guide when you can’t read or speak the local language?

It should be visual.
Lots of pictures and maps to show you what’s where and what it looks like.
The “wayfinding” information should be visually separated from the description information.
Information such as place names, metro stations, bus numbers, should be easily distinguishable on the page so easy to point at. It shouldn’t be hidden in a large block of text.
It should be easy and quick to find information on the page.
It should have clear, easy to read maps that are accurate and which can be read inside and outside a building (that is, under different lighting situations).
It shows the names of places written in the local script as well Roman script.
It should also include how to pronounce the name.
It should include a comprehensive list of commonly used words and phrased (and how to pronounce them). It should also include translations of common phrases found on signage.
It should include a metro map (when there is a metro).

Would I visit Russia again? You bet! I found everyone (except perhaps the ladies in the metro station ticket desks) friendly and helpful. I know which travel guide I’ll be bringing with me.

August 28, 2012

What’s your name?

by Jen O Neill

I watched many TV hours of the recent Olympics in London. I hadn’t expected to get so involved with it but it was fantastic. The British put on a wonderful games. Listening to the BBC sports presenters discussing the various events, I noticed that the names of many athletes also caused discussion. It wasn’t always obvious to TV presenters how to spontaneously pronounce some names. Husain Bolt runs off the tongue but Gulden Kayalar Kuzubasioglu may need some prior thought. Several presenters admitted to practising names beforehand. I’ve no idea if they were correctly pronounced.

The BBC journalists at this year’s Olympics haven’t been the only ones to have had problems figuring out how to pronounce the names of athletes. When personal names move outside of their usual cultural environment, you might need some help when faced with an unknown personal name. This site is worth visiting to hear names pronounced correctly.

But my name is….

First impressions (from an Anglo-Saxon perspective) suggest that my name, Jennifer O Neill, is straightforward to write and pronounce. However, one consequence of moving around between different countries and languages is that your name can take on unforeseen new meanings. To date I’ve lived in five countries and two languages and my apparently simple name has had some unexpected surprises.

My surname is one of the most common Irish surnames so it’s easy to assume that everyone everywhere is familiar with it, particularly as Irish pubs are found all over the world and they tend to be called after Irish names. Bad assumption.

There’s no apostrophe in my surname but there is a space as my surname is two words. This “hole” in the name can occasionally cause confusion. Many people don’t expect a word in a name to have only one letter. Sometimes when I enter my name in an online form, the form automatically assumes the “O” is the initial of my middle name and that my family name is “Neill”. Americans often write their names with a middle initial so I’m possibly falling foul of a form design planned for this habit. The W3C has a useful site on the cultural aspects of personal names when designing online forms.

You mean it’s a real name?

As a kid in Montréal, I went to the local French-speaking school and I was called Geneviève, the French for Jennifer. So years later when I moved to Paris, I wondered whether I’d again be called Geneviève.

The French have no issues with “Jennifer” (even though “Geneviève” is one of the patron saints of Paris). It was always pronounced and spelt correctly. However, when pronouncing my surname I had to learn to listen out for “Jennifer Onaay”. C’est moi! The spelling problems always involved the double “L”. I always just received one.

Moved on to Brussels and another unexpected identity change. No francophone pronunciation this time, however. It was when out shopping and paying by plastic that my new identity appeared. Several shop assistants were surprised by my surname on my payment card. “You mean it’s a real name?” For them “O’Neill” is a mark of sportswear (they never notice the lack of apostrophe). They continue to find it extraordinary that I’ve been named after a brand of wetsuits. I may as well be called “Jennifer Adidas” or “Jennifer Nike”.

So does that mean that for many people around the world anyone called “MacDonald” is named after a …?

And another identity pops up….

We should have expected that that hole in our surname might cause problems. A Chinese client of my brother in Canada would always phone the company’s reception and ask to speak with “Mister Shanee One Ill”. We had previously never thought about moving the hole. But if “o neill” makes no sense to you, “one ill” at least is two recognisable English words. Indeed keeping up with how one’s name is pronounced and possibly battered around the world could sometimes require an aspirin.

Has your name changed identity?

Has your name changed in meaning or pronunciation when used outside of its usual cultural circle? What stories do you have of your perhaps unexpected new identities in an increasingly global world?

July 11, 2011

Working with OEM documentation

by Jen O Neill

Outsourcing manufacturing is big business. Many companies today use the services of other companies to make, even design, some of their products as it can provide them with needed components or products without owning and operating a factory to do this work themselves. The benefits are cost savings, improving time to market, and access to a wider range of products than they could develop themselves in-house. Both hardware and software are outsourced.

What’s an OEM?

Companies to whom manufacturing is outsourced are called Original Equipment Manufacturers (OEMs). An OEM is a company that “manufactures goods that are sold to other businesses that might rebrand them and sell them at retail”. Source of OEM definition.)

An Original Design Manufacturer (ODM) is a company that “designs and manufactures a product which is specified and eventually branded by another firm for sale”. (Source of ODM definition.)

OEM and ODM products are used in many industries, but particularly so in electronics. These companies are located around the world but many are based in Asia. In this article “OEM” has been used to cover both OEM and ODM companies.

The OEM source files

If you are rebranding or rewriting OEM documentation, be aware that in the world of OEMs, Microsoft Word rules. As cost control is a big issue with many OEMs, few have technical writers in-house but instead get their engineers to write the documentation. They use Word.
And often they’re not writing in their mother tongue – most OEMs aren’t located in English-speaking countries. The documentation consequently can often be poorly written and riddled with an “English” contaminated by another language.

Rewriting OEM manuals can be challenging, particularly if you’re working to a tight deadline and the English is poor. If your company works with many OEM products, a further challenge is trying to keep the rewritten manual consistent with the content of the other manuals in your company. Reuse of content is particularly important to help control translation costs. Yet writing for reuse can at times feel a challenge when you’re struggling with reading to comprehend, particularly if you don’t have access to the OEM engineers to ask what they meant in the text they wrote.

Some companies just simply rebrand an OEM manual and leave the content as is. There are unfortunately many examples of such manuals on the internet. Lots of companies don’t have the services of technical writers. And don’t consider the business benefits of having them either.

Keeping terminology correct and consistent

Working with OEM software and documentation increases the need for terminology control as there’s a greater chance of unapproved, inconsistent, and incorrect terms being present than when content is developed in-house. Even when correct, terms may also not always be the same between companies.

Build a glossary of terms related to your OEM documentation and software that includes both the correct and incorrect terms. Include context of use, the definition of the term. So next time a writer in your group is working on an OEM manual and they come across “appearance time”, for example, they can quickly look it up in the glossary and see that this must be changed to “display time”. As with all glossaries, this is a living document and must be regularly maintained.

Fluency in other languages is certainly a help when working with OEM documentation as it can make it easier to spot problems with terminology. One example we had of “flavoured” English was in the software of a French ODM we used to develop a program for us. They used the term “equipments” throughout the English source software. We changed this franglais (English with French influence) term to “devices”. The word “equipment” exists in both languages but the context of use can differ. In French this is called a “faux amis” or “false cognate” in English. Be continually on the lookout for such faux amis when checking software and documents written by OEMs.

Where possible, give the OEM your company’s glossary of approved terms to use when customizing products for your company. But continually check that your company’s approved terms are indeed being used, particularly when the product is updated. A different engineering team perhaps might be put in charge of the product update and for whatever reason they could ignore or overlook your glossary. Stay alert.

Legal issues

Reuse as is or rewrite the OEM documentation? This question will be answered in the contractual agreement drawn up between the OEM and the company using their services. It will specify whether the product documentation will be handed over by the OEM to be customized. So if you have any specific documentation needs, such as you want to the source files in XML, FrameMaker, or HTML, for example, you should ensure that this is agreed upon before any contractual agreement is signed. But as stated earlier, most OEMS work in Word.

In my experience, many OEM manuals have incomplete or no regulatory information included, where required. If you are rebranding/rewriting OEM manuals, check that all required legal information is indeed included for your market. Although legally the manufacturer is responsible for placing the CE mark on the product, for example, once you rebrand it, you then become legally responsible. See an earlier blog on sharing source files with third party companies.

Localisation issues

In my experience, few OEM companies consider the impact of localization on their software and documentation even if they are selling their products worldwide. And that includes OEMs with in-house technical writers.

If you will be translating the documentation you’ve inherited from an OEM, you should review it for potential localization issues such as embedded text in graphics (do you have the source graphic files or just the jpeg files?), terminology (mentioned earlier), and possible cultural issues in the content. One OEM my company worked with had in-house native English-language technical writers who targeted their documentation to the America market although the OEM sold its products in many other countries. They had, for example, used the term “Thanksgiving” in a section of a user manual on programming schedules instead of the generic “public holiday”. We had to carefully go through their manuals to ensure that the content was culturally neutral for our market in Europe, Middle East, and Africa.

In summary

From the contractual agreement and your product managers, find out what has been agreed with the OEM with regards to the documentation.
Develop a glossary specific for this OEM (or expand your group’s glossary) that includes correct and incorrect terms.
Check that the legal information in your rebranded/rewritten documentation is correct and complete.
If you translate, check for potential localization issues.

May 23, 2011

What’s the most important time zone in Europe?

by Jen O Neill

Working for an American multinational company with technical writing colleagues on both coasts of the US and me in Belgium, you’d think I’d be watching the clock to see when they’re in the office so that we can talk.

Nope.

I’m not watching the Instant Messager screen on my computer to see who’s available in the US. It’s my colleagues across Europe that I’m tracking. I often need them at short notice for information.
So which time zone matters the most to me when trying to get hold of my European colleagues during the day?

Lunchtime!

Between time zone differences and cultural differences on when to eat that exist between European countries sometimes I sometimes feel that I’ve been thinking about lunch for much of the day. If it’s X time, then A must be at lunch. And at X+1 time, B and C will be at lunch. C is at lunch at X+2 time …

From 11:00 in the morning (my time) my Finish colleagues aren’t around. It’s noon for them and they’re at lunch so no point chasing Finns then. An hour later, it’s my lunch time. So the German, French, Dutch and Italian colleagues know they won’t have me pinging them as we’re all at lunch.

By 14:00, my time, there’s no point contacting colleagues in Britain for information as it’s 1pm for them and they’re gone to lunch (except they’re not gone for long). In the past my Spanish colleagues would be off to lunch at 14:00 and often not return until near 16:00. So for a few years I was tracking a lunch time zone that could last up to five hours yet I never left Europe.

For many of us in Europe lunch is a main meal and not a grab-n-gobble sandwich at our desks. Sadly the two-hour lunch no longer (officially) exists in our European offices. When I moved to France from Britain years ago, I quickly adapted to a slow two-hour lunch with colleagues. The company canteen served a five-course meal with wine or beer. I then moved to Belgium to work for another company and lunch became an hour. Only one hour!

Working in a corporate environment can mean that local habits change. I can’t remember when the two-hour lunch disappeared in our French office but when we were bought by our current owner, they insisted that the Spanish office fall into line with the rest of the offices in Europe. They had to eat earlier and come back in an hour. They weren’t happy about that. These days I can ping Spain at 14:00 and get a reply.

My lunch time zone now at work is only around three hours.

Bon appetite! (Now if you could just get that info back to me by…and pass the salt. Thanks)

January 27, 2011

No Weather in Belgium

by Jen O Neill

I’ve been thinking about the recent travel chaos that hit Europe and North America over Christmas when air travel practically came to a standstill for days due to the snow. Like many, I was stranded and sought information everywhere and anywhere in an attempt to figure out when I might be getting off the ground. Internet, radio, TV.
Watching the weather forecasts on French TV, I noticed that the weather curiously stopped at the French border. Changing channels to a Dutch station, the weather there stopped at the Dutch border. Same phenomenon on German TV; no weather outside Germany.

Did this mean that there was no weather in Belgium, situated between these three countries?

Not at all. Belgian TV showed me that the country was indeed having its own enclosed microclimate and not sharing it with its neighbours either. But as a stranded air passenger, I was aware of the larger picture-that all these countries were indeed sharing their weather and that by sharing their weather, the weather was having a much bigger impact than if it had stayed as numerous microclimates.

It’s not just TV weather news that can be accused of confining themselves within self-imposed borders. We can be guilty of it, too. Restricting our thinking and work within the confines of our own boundaries, such as narrow functional responsibilities, is unfortunately too easy to do. Silos can seem such comfortable places. Both for us and the information we produce as writers. How much information in our style guides, for example, could be used by other groups in the company but is never shared or has not been set up to be shared? Perhaps they don’t even know we have it. And what do they have that could be useful to us?

And yet, just as the weather has found, we can make a much bigger impact if we get out and collaborate with others. It can be hard to step outside the comfort zone. Yet if we want to develop and succeed professionally, we need to think outside of the box.

We need to be more like the weather. Circulate.

October 4, 2010

Sharing our source files with other companies

by Jen O Neill

Earlier this year, Tom Johnson in his blog “I’d Rather Be Writing” discussed the issue of documentation ownership. He had recently handed over the source files of several manuals he had done to an internal client and felt that the manuals had been “stolen” from him. He acknowledged that it was the loss of “ownership” that unsettled him. He no longer controlled the quality of his documentation.

Ownership does matter

The topic caught my attention as I regularly exchange source files with customers, developers and our sales offices. Where I differ from Tom is that I am often exchanging source files with those from outside of my company. “Ownership” takes on a legal context in such situations. Whatever I may think about a document being “mine”, it really does matter to my company what happens to it after we hand it over and who becomes responsible for the content.

Sharing files in a collaborative age

In my product group at work we regularly share source files with third party companies. Several of our products are manufactured by original equipment manufacturers (OEMs). We receive their source files of the accompanying manuals to customize for our market needs as well as to rebrand.

Occasionally a large customer may request that we customize one of our product to suit their market requirements, which will mean the documentation too. Usually we would customize the documentation in-house but not always.

Not everybody wants English. Many of our customers don’t operate in English. As we operate globally, we translate into many languages and they may want their language to be customised. A large Danish customer, for example, wanted our Danish translations customised. As we couldn’t do such work ourselves, it was agreed that we’d hand over the Danish source files to them for them do rework and rebrand. They also wanted to customise our Swedish translations themselves.

And everyone wants the source files in Word. Microsoft Word is the common tool between us all.

Signing a contractual agreement

Sharing source files with third party companies — whether receiving source files from OEMs or handing over source files to external customers for example — means that as writers we should be aware of the legal implications. Obviously we shouldn’t blindly hand over source files whenever an external customer requests it.

There must be a contractual agreement drawn up between two companies and one of the items covered will be document customization. This agreement will state whether your company will do the customization in-house or if the source files are to be handed over to customers for them to modify the documents under their responsibility.

Handing over source files to customers

Before handing over source files to a customer, you need to ensure that:

Your company branding has been removed—Your company branding must be removed such as company logos, propriety fonts, and any company branding colours. Proprietary fonts, or example, could be changed to a general font such as Arial.
The copyright statement has been removed—Unmodified manuals used by customers remain the property of your company. However, if any changes to the contents of the manual are made—including simply replacing your company’s logo with that of the customer—you need to remove your company’s copyright statement from the manual and replace it with the customer’s copyright statement as they are now responsible for the content. The customer then also determines the legal front matter text to be used.
The customer has signed the legal agreement—Before handing over source files to a customer, the customer must sign a license and indemnity agreement drawn up by your legal department. Normally it’s the product manager iwho’s responsible for ensuring that the customer signs the agreement and for keeping the signed copy.

Customising third party documentation

The contractual agreement drawn up with the supplier, such as an OEM, will specify who is responsible for customizing the technical documentation and its maintenance. By customising the contents of the supplier’s documentation to meet your company’s requirements, your company then becomes responsible for the content and its maintenance.

You also need to consider regulatory requirements and how they impact the supplier documentation that you are customising. Products branded as your company’s products, or products imported by your company into a regional market such as the EU, must comply with the applicable regulatory requirements (such as European Union directives).

Under new ownership

There are going to be times when we have say goodbye to our work and wish it well under new ownership. Although as technical writers we can often be loath to handing over our source files to customers for fear of the impact on quality, exchanging information is part of doing business. Our work is part of business. We need to know what’s involved when handing over source files to third parties so that we and our companies don’t get any nasty surprises later on.

May 25, 2010

Open plan or cubicle?

by Jen O Neill

I’ve been reading up recently on agile environments. I don’t work in such an environment but have been struck at how often they discuss the importance of the office layout to encourage collaboration in a team. The preferred layout always cited is the open plan office.

The layout of the workplace does impact productivity. An open layout encourages communication between people. It’s a more dynamic place to work as it allows team members to interact more easily. The downside is it can be distracting if you need to concentrate. Cubicles encourage solo work, where less interaction is required. However, cubicles can discourage that cross-fertilisation of ideas and exchange of information that comes with close teamwork. Another disadvantage of cubicles is the potential risk, “Out of sight, out of mind”.

The culture of the workspace

There is also a cultural aspect to office layout to consider. Most Europeans work in open plan and most Americans work in cubicles. I’m not sure why this is. Which office layout you prefer may well depend on which you’re used to.

I’ve never worked in a cubicle. I’ve only worked in an individual office or in an open plan layout with up to six people. I’ve never worked in offices with large areas of open plan (+40 people).

Team benefits

In the agile environment you are located in your team. As my projects are determined by Product Management, I’m physically located with that team (I actually report to them). However, I don’t feel isolated from the other writers in the company, who are all located in other countries anyway. I’m in frequent contact with them by Instant Messenger and we chatter about tech comm. related topics and what work is like at our respective sites.

I’m an open plan person. I savour the opportunities to have ad hoc conversations with people, eavesdrop on the telephone conversations of the product managers around me and exchange ideas. I hear about customer evaluations as well as learn about the wider picture of product development and on doing business with suppliers (whose manuals I will be rewriting and with whom I will also be contact). I believe that this helps me collect a wide range of information to better focus the manuals I write and localise. I don’t want to work in a cubicle as I would find it isolating.

In my opinion, an open plan layout of, say, up to eight people is great for encouraging team collaboration. A larger team would probably need a careful review of the different types of workspaces that should be provided to balance team needs and solo work moments (for example a mix of individual desks, meeting desks, places for quiet work, hot desking…).

Coping with noise

Open plan can sometimes be distracting. There are four of us in the office and between us we have six mobile phones and four landline phones. We’ve reached a “gentleman’s agreement” not to use loud “amusing” dial tones on our mobile phones and to use the headsets provided for teleconferences (unless others are invited to listen in). If I really do need silence to concentrate when working on a project, I stay home that day and work from there.

Which layout do you prefer to help you do your work: Open plan or cubicle? What different types of office layout have you work in and which have helped you feel part of a team?

March 30, 2010

Happening times

by Jennifer O Neill

I work in the manufacturing sector and many of our products are outsourced to suppliers for development and manufacture, to be sold under our company’s brand name. The English terms I come across in the software and manuals that I check can often be amusing in their originality. A Chinese supplier with whom we work called the term “Event” in a product’s firmware “Happening Time”. I don’t know why but the term “Happening time” tickles me. I still changed it to “Event”.

I’ve no idea how “Rule” became “Handle”.

I may find amusement in such mistakes but on the down side….

Over the years I’ve worked with over two dozen suppliers from around the world, most in Asia. Only two of these suppliers have used technical writers to do their manuals. One was in Canada and the other in Israel.

It was a few years back and at the time neither writing group in these two companies gave sufficient thought to the impact of localisation on their manuals (such as text expansion and embedded text in graphics) as they didn’t translate their work. Yet their companies were selling the products to other companies for resale under other brand names, and these companies often operate in multilingual markets. Such as my own company. I may have had to redo the layouts and graphics of their manuals for localisation, but the English was correct.

I hope that these two writing groups are now doing manuals that are easy to localise, even if they’re still not doing any translation themselves. Such a step would increase the value of their services to their respective companies, who are keen to expand internationally.

However, most of the “English” source documents I receive to customise for my company are written by engineers in non-English speaking countries. The level of English varies from “Nearly there” to “????”.

The standard localisation issues with text expansion, embedded text in graphics, and inconsistent terminology are obviously also present. The Tech Comm world may be a buzz with XML and DITA but Microsoft Word is doing great in the world of many companies. So is Normal style. These issues are easy, if perhaps time consuming, to fix.

What does shock me is how many companies release manuals and software with poor, at times incomprehensible, English. If you then plan to then translate the documents and software, poor English will then often mean even worse translations. And translating isn’t cheap.

Training technical writers isn’t the problem. It’s training companies to have higher expectations on the quality documentation and software they provide to customers. Customers matter. Being able to use a product easily matters. Crap English impacts your bottom line.

Companies also need to realise that being able to speak English sort of OK isn’t the same as being able to write it correctly. Users – and translators – can tell the difference.

I know that English-mother tongue or fluent writers aren’t easy to find in many of the new growing industrial areas of the world. One of our Chinese suppliers is now getting a Chinese engineer who lived in the US for several years to do their manuals. The English is better (from a low base line). It’s still foreign-flavoured English, but it is at least easier to understand and is a step in the right direction for the resources they have at hand. Realistically, the chances of them hiring a mother-tongue writer in their city are minimal. We still rewrite their documentation for our customers.

Last year, I attended the STC France annual conference. During the last session when the speakers were discussing how they thought our profession would evolve in the future, one speaker said that we would be spending more time rewriting other people’s work. I agree.

English is now the linga franca of international business. As a result, the quality of English is often suffering. The challenge we face is finding ways to improve written English in documentation, and to persuade companies it’s worth the investment. Let’s reduce the incidence of all those awful happening times.