TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Lisa Bronson wonders: <<Have you ever put vendor documentation in your
instruction manuals?>>
Not directly, but I've often rewritten information from vendor docs where I
felt it was important. If I want the reader to know something now rather
than shuffling several manuals to find something (e.g., in
mid-installation), I repeat the vendor information in my own words, and test
to be sure my rewording is correct. If the reader can look the information
up later, I refer them to the vendor manuals.
<<Our machine are made up of hundreds of parts, some of which come with
vendor documentation. My manager told me this afternoon that one of the
engineers suggested we include some of the vendor documentation in the
appendix of our manuals.>>
You shouldn't blithely copy someone else's information without their
permission (copyright!!!), but you can certainly present your own summary of
what you consider important. As a design goal, put yourself in the reader's
shoes: Do you really want to be shuffling "hundreds" of vendor docs (one per
part in your machine), or do you want everything put together in a single
convenient package? The latter, obviously, and that means you should be
writing your own text based on the vendor materials.
Obviously, for more complicated situations it may make much more sense to
obtain the right to reproduce the materials produced by the vendor in your
own docs. That's particularly true if the vendor docs are complicated and
long; no point repeating all that hard work. In that case, you can sometimes
provide a high-level overview. For example:
Step 1. Install thing A (Ch. 3 of Vendor A manual).
Step 2. Install thing B (Ch. 7 of Vendor B manual)
Step 3. Combine A and B (Ch. 2 of this manual)
One note: I've been doing this lately for some systems based on electronic
dataloggers, and frankly, the vendor's documentation sucked so badly I
wasn't remotely tempted to include it verbatim. That was a motivation to use
the vendor docs as source material for my research, but do the grunt work
myself to produce something helpful.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"Writing, in a way, is listening to the others' language and reading with
the others' eyes."--Trinh T. Minh-Ha, "Woman native other"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
