Manual writing
Thread poster: flarrazabal

flarrazabal
Japan
Local time: 17:42
Member
English to Spanish
+ ...
Dec 8, 2010

I don't know where to post this topic.

Does anyone have experience writing technical manuals (not only translating them)?

Should manual writers always have access, on-site or otherwise, to the product?

Do technical writers write the manuals after testing the products and testing the features with the engineers and/or designers?


 

Soonthon LUPKITARO(Ph.D.)  Identity Verified
Thailand
Local time: 15:42
Member (2004)
English to Thai
+ ...
Software Dec 8, 2010

I understand that FrameMaker is one of the good software for user manual writing. That is, it contains feature for very good conditional texts (e.g. male/female version of manual etc.), hypertext strings and others. Manuals today are both in printed paper and electronic forms e.g. PDF, html that are better to search for particular key words. Reading a FrameMaker program manual to know more how to write a better technical manuals for electrical appliances, automobile etc.

Soonthon Lupkitaro


 

Nicole Schnell  Identity Verified
United States
Local time: 01:42
English to German
+ ...
How else could you write about a product? Dec 8, 2010

Fernando Larrazabal wrote:

I don't know where to post this topic.

Does anyone have experience writing technical manuals (not only translating them)?

Should manual writers always have access, on-site or otherwise, to the product?

Do technical writers write the manuals after testing the products and testing the features with the engineers and/or designers?



Of course you need to have access to the product. You need to see it, touch it, watch how it works, and - most important - know how to operate it. I used to write a lot of brochures for a client in the power and automation industry. I traveled a lot and got to know each machine in person. Smaller gizmos (I attended to their medium voltage products) I would even take home and at times they were piled up not only at the office but also in my apartment. Because those things had to go to the photographer I had to learn how to operate them myself because the photos needed to show a particular screen on their displays and such. Only when you know the product inside out you are able to write about it.


Apartment, not appartment. Sorry.icon_smile.gif

[Edited at 2010-12-08 08:54 GMT]


 

flarrazabal
Japan
Local time: 17:42
Member
English to Spanish
+ ...
TOPIC STARTER
Under development Dec 8, 2010

Thanks a lot for the information about a basic question.

I'm having some issues with having the right person who can do the writing but lives too far away from the manufacturing place and, in many cases, the manual will be written while the product is under development.

Right now, the DTP software is not an issue.


 

Nicole Schnell  Identity Verified
United States
Local time: 01:42
English to German
+ ...
@Soonthon LUPKITARO Dec 8, 2010

Soonthon LUPKITARO(Ph.D.) wrote:
conditional texts (e.g. male/female version of manual etc.)


Eventually you have to explain to me what a male/female version of a manual is. icon_smile.gif


 

Nicole Schnell  Identity Verified
United States
Local time: 01:42
English to German
+ ...
Depends on the product Dec 8, 2010

Fernando Larrazabal wrote:
I'm having some issues with having the right person who can do the writing but lives too far away from the manufacturing place and, in many cases, the manual will be written while the product is under development.


Video might be sufficient. It's involved and time-consuming but less expensive than travel. Also: LifeCam - most laptops are equipped with that.

???


 

Jaroslaw Michalak  Identity Verified
Poland
Local time: 10:42
Member (2004)
English to Polish
Engineering staff Dec 8, 2010

All technical (product) writers I met were employed on-site. In fact, most of the teams (because rarely it has been a one-person job) included the engineers who have designed the product in question...

This worked particularly well if they were involved in the translation - for example, when I asked about a specific detail, I could get an answer like "today I crawled under the machine and the bit you are asking about is..." etc.


 

José Henrique Lamensdorf  Identity Verified
Brazil
Local time: 06:42
English to Portuguese
+ ...
User friendliness Dec 8, 2010

First of all, let's handle this issue...
Fernando Larrazabal wrote:
Right now, the DTP software is not an issue.


Absolutely correct! While a most dazzling online manual made with Flash can be completely useless, a good, user-friendly manual, could be obtained with Windows Notepad.

I have translated, written, rewritten manuals for various things: heavy and light industrial equipment, organizational procedures, software, home appliances, etc. IMHO the key issue is user friendliness. The whole purpose of a manual is to teach the reader how to do something. It's not the proper time to show off our resourcefulness and creativity in DTP... nor in using the language. The writer must take the user's stance, and write in their language.

I have in my mind one article I still intend to write about conquering user loyalty via user manuals. If the instructions enable the user to benefit from the use of all the features provided by one product brand, s/he will see that product as 'better' than an equivalent one where exactly the same features are hidden beyond their reach.

I've had a whole lineage of XXX-brand cell phones. From the first one, that was able to make phone calls and store a dozen phone numbers, all the way to the current one, where I probably use some 5% of all its available resources. I chose the brand for no particular reason, maybe just because a distant cousin once was a big shot in another division of that company.

These 5% are the likely reason why the present one will be the last cell phone I intend to have from that company. What they consider "intuitive"... well, their intuition must be quite different from mine. Yet some pencil-and-paper tests unanimously say that I am an intuitive type.

The user manual starts out under the assumption that I got that cell phone for entertainment, while I don't have any objection to make and receive phone calls while being amused by it. Quite frankly, I'd settle for a dial - not touch-tone - cell phone, since it's all I expect.

The manual was written by engineers (and I am one!) exclusively for their practicing peers (nope, I am a translator). While it covers some 60-70% of the features available (the others are deemed to be 'intuitive'), it uses phrases like (I'm inventing and overdoing it here, but that's how it sounds to me) "If your provider is DCPPTX-enabled, you can WPCX your TLOB to GGT up your XNPQ."

So I think there should be a market for rewriting good, user-friendly manuals. One last-ditch possibility is to give the writer a working unit, specs, etc., but this would take a lot of time, and the writer would have to research on the technology used, to complement with recommendations. Not very efficient.

A better option is to provide the writer with a complete set of explanations, prepared by the engineers who developed the product, some light and pragmatic reference literature on the technology involved, and the phone number of a guru to answer any questions. Depending on the product to be covered, a working unit may be needed or not. Let them organize all that information in the way a new user would like to absorb it.

To illustrate, in most or all software manuals I have, Chapter One focuses on installation. If the thing is any good, installation will be done once in a lifetime. So in all software manuals I wrote, the first page says: If you haven't installed it yet, stop reading, go to Appendix A, and do it by following the instructions there. After you are done, come back here, and resume. The result is that when the user later comes back to the manual for guidance, they won't have to skip (turn, one by one, the pages of) all the installation instructions before getting to the beginner's tutorial or walk-thru. Appendix B covers permanent data backup and uninstallation.

This is just one of the many items to be considered by the manual writer. Check any car manual. You open it for information, and start reading... Congratulations! You are now the proud owner of a... blah, blah, blah. Suppose you took your daughter's car (where maintenance is rather lax, her boyfriend is studying Law) for a drive, and noticed that the steering pulls to one side. One front tire looks a bit deflated, compared to the other. How much pressure are you going to put there? How long will it take for you to find that information in the car manual? Then the right headlight won't go on. Is it the lamp or the fuse? You pop the fuse box open, see it has an array of spare fuses, but where is the one for the right lo-beam headlight? The cover you removed has many "international" drawings with numbers, hard to read in the dark. Manual again! How long wil it take you to find the number for that fuse described in plain text?

Yet I haven't seen any car having a quick-reference card with just the most likely nformation that a driver might need quickly. The MSDS on coolant fluid might be entertaining while you are waiting under the rain or snow for a tow truck to come, however it's useless if you are in a fix.

So there would be a huge market in good manual writing, if manufacturers didn't supply instruction manuals only because they have to, but to ensure that their end-users get the best and the most their products can offer.


 

Riccardo Schiaffino  Identity Verified
United States
Local time: 02:42
Member (2003)
English to Italian
+ ...
How right you are, José! Dec 9, 2010

José Henrique Lamensdorf wrote:

If the instructions enable the user to benefit from the use of all the features provided by one product brand, s/he will see that product as 'better' than an equivalent one where exactly the same features are hidden beyond their reach.


How right you are. Engineers, too many technical writers, and bad marketing people concentrate on features.

Users need to know about benefits.


 

Veronica Lupascu  Identity Verified
Netherlands
Local time: 10:42
Dutch to Romanian
+ ...
technical writers Dec 9, 2010

Fernando Larrazabal wrote:

Should manual writers always have access, on-site or otherwise, to the product?

Do technical writers write the manuals after testing the products and testing the features with the engineers and/or designers?


Technical writers certainly need to see/test/use the product to be able to write about it. I don't have experience myself, but even creative writing needs a real/tangible source of "inspiration". I read somewhere that technical writers for Harley Davidson motorcycles are required to be able to disassemble and assemble back the motorcycle itself. Maybe they request the same from their translators, who knowsicon_smile.gif


 

Jennifer Barnett  Identity Verified
France
Local time: 10:42
Dutch to English
+ ...
engineer and user have completely different perspectives of a product Dec 9, 2010

So often I am frustated by having to wade through WHAT wonderful functions a thing can do but there is scant information on HOW to bring these wonderful functions to life, especially the more mundane aspects like how to get the photos in your mobile phone onto your computer. For example, as José said, "If your provider is DCPPTX-enabled, you can WPCX your TLOB to GGT up your XNPQ"; it is not explained HOW 'you can WPCX your TLOB'.

To my mind, the writer of the manual should certainly not be the creator/designer of the product because their point of view is completely different from that of the user. Obviously their consultation is needed! Now that I think about it, presumably the process of creation and getting a product to work is largely based on intuition built up after years of learning and experience so it is unreasonable to expect the same person to be able to explain how a novice should use their creation. It's as if the apparatus is a high wall and the engineer and user stand on opposing sides. Actually, it is probably best if the manual writer initially knows very little about the apparatus to avoid falling in the trap of writing implicitly.

I'll stop now before this develops into another grumpy-old-lady rant.


 

José Henrique Lamensdorf  Identity Verified
Brazil
Local time: 06:42
English to Portuguese
+ ...
Advantages vs. benefits Dec 9, 2010

Riccardo Schiaffino wrote:
Users need to know about benefits.


IMHO knowing about them is not enough; they must be enabled to use these benefits.

My "engineering and marketing" background, aka "industrial marketing", later complemented by a "training & development" one, leads me to envision the situation in a mathematical equation:

Comparing products A and B:
advantages = features (product A) - features (product B)

Of course, if the result is negative, product B will be seen as better.

However an advantage only turns into a benefit when the end-user actually benefits from it. To benefit from an advantage, the end-user must have a need or want to use it, and consequently must also be enabled to use it. If an advantage fails to convert into a benefit for an individual user, it's just as if it weren't there.

"Enabling" involves explanation and training on the use of these features/advantages. Manufacturers spend millions in R&D to develop exclusive features, but then try to save a few pennies in each manual at the expense of not fully enabling users to benefit from them. Even if they occasionally do invest in the original manual, quite often they export, and then try to save a few pennies by using overly cheap - or even free machine - translation.


 


To report site rules violations or get help, contact a site moderator:


You can also contact site staff by submitting a support request »

Manual writing

Advanced search







BaccS – Business Accounting Software
Modern desktop project management for freelance translators

BaccS makes it easy for translators to manage their projects, schedule tasks, create invoices, and view highly customizable reports. User-friendly, ProZ.com integration, community-driven development – a few reasons BaccS is trusted by translators!

More info »
WordFinder Unlimited
For clarity and excellence

WordFinder is the leading dictionary service that gives you the words you want anywhere, anytime. Access 260+ dictionaries from the world's leading dictionary publishers in virtually any device. Find the right word anywhere, anytime - online or offline.

More info »



Forums
  • All of ProZ.com
  • Term search
  • Jobs
  • Forums
  • Multiple search