Product manual writing in a small company
Product manual writing in a small company
(OP)
My company's product manuals are in need of an update and revisions. I've been handling basic minor revisions, but lately it's clear we need to re-evaluate them on a much higher level. We coasted long enough and need to get back to these in earnest.
What I think we need is a technical writing person or specialist. But we're small enough that we don't have that position (hence the current situation). If you're like us, I'd like to get your thoughts.
Do any of you have technical manuals being written without a professional technical writer on staff?
How do you determine the appropriate writing style?
Do you routinely submit your things to a legal department, or do you use a pre-arranged set of guidelines to keep things "legal"?
How did you decide what (if any) bonus documentation is appropriate (youtube instructional videos, DVDs, etc)
Thanks,
David
What I think we need is a technical writing person or specialist. But we're small enough that we don't have that position (hence the current situation). If you're like us, I'd like to get your thoughts.
Do any of you have technical manuals being written without a professional technical writer on staff?
How do you determine the appropriate writing style?
Do you routinely submit your things to a legal department, or do you use a pre-arranged set of guidelines to keep things "legal"?
How did you decide what (if any) bonus documentation is appropriate (youtube instructional videos, DVDs, etc)
Thanks,
David





RE: Product manual writing in a small company
Who is going to read this manual, the general public? Other engineers?
What are the consequences of the reader not understanding the manual? Will it void the warranty? Will the reader or someone in their vicinity, get killed? Both?
Is it good or bad for someone to post your video up on YouTube?
--
JHG
RE: Product manual writing in a small company
You have to develop a step by step mindset. Take excruciatingly clear notes as you go through the process step by step. Then have someone who knows nothing about the process try to follow your directions. The take drawoh's advice into consideration and run it by an attorney if you feel you need to.
I have never had any luck with hiring technical writers. They just don't have enough background.
As you become more and more familiar with a machine the process of running the machine becomes more automatic. When you try to write instruction you tend to leave out parts you do automatically.
Thomas J. Walz
Carbide Processors, Inc.
www.carbideprocessors.com
Good engineering starts with a Grainger Catalog.
RE: Product manual writing in a small company
Technical writers know how to write, but don't know how your product works at all. You cannot simply hire a technical writer with a PO that says "Write a manual for my product" and expect a decent result.
The writer should come in, interview the engineers, designers, assemblers and the field service team.
RE: Product manual writing in a small company
We already have the step-by-step stuff pretty well figured out. It's the style, legal, media, distribution, etc. questions where we'd like to take our manuals as they are today and elevate them to be better. (For several years we tweaked and updated content but no format changes. Youtube didn't exist and digital cameras were scarce.) We need to ask ourselves the questions that drawoh is asking and provide sensible answers that legal, sales, engineering, marketing, customers, etc can all live with. Then we need to allocate the right resources to follow through on the new plan.
I have found the case as MintJulep - a few engineers are skilled writers, but not many. And those who can write, write in their own way - it is not done with the style of properly planned technical writing.
David
RE: Product manual writing in a small company
as for contents: a clear distinction should be made between legally required stuff, necessary safety information, warranty descriptions and actual instruction on how to use and maintain the equipment. the style for the various items will vary - safety and legal matters usually require a more or less strict and predefined format. in the actual operating instructions you will have more freedom.
writing a good operating manual is no easy task. even if you think you have described everything there is to know and what to do/do not, there will always be users that will operate the equipment in unforeseen ways. that may end up in legal claims or warranty claims or both. therefore a very precise and comprehensive instruction may be required.
the instruction manual should contain a number of different sections. usually a short description of the equipment, what it can do and how, which buttons, levers etc have which effect and so on. that is no user instruction as such, but more a explanation about the use of what he will get instructions.
the actual user instructions contain operating instructions, maintenance instructions and perhaps a fault finding guide. operating instructions instruction should be clear: not only what does what but also why and in which circumstances a particular feature should be used. in a lot of manuals the last part is more or less left out - the operator does now what button has what effect but he still may have no clue where that might be useful.....
most manuals will be improved by including drawings and images. if you do, make sure they exactly show the equipment as the user has it - if not it will add confusion. a video may be helpful - if made well, which tends to be very costly.
technical writers may be able to do the writing for you, if properly instructed. that means instructing them on the use, purpose and maintenance of the equipment and to give them enough time to familiarize them with the machinery. after that they can start writing. when the first edition of the text is ready it is a good idea to give it to some people that are not yet familiar with the equipment and see what happens. you will be in for a few surprises and get quite a few ideas on how to improve your instructions! eventually you will end up with a suitable text, after considerable time that is.
if you have it done in-house other difficulties may arise. most engineers are not very good writers. and if they are, they tend to assume quite a bit of knowledge already available to the reader - which means they may tend to leave out some necessary steps in the instructions and thus the buyer will not be able to operate the equipment.
maybe the best solution for a small company is to establish a working relationship with a local technical writer actually interested in the equipment you manufacture and consult with him already during the design and testing process. he might have useful suggestions on communication and ergonomics and also will gradually learn what the equipment can do and how to describe that in more or less layman terms. all in all it will take considerably more time then just the writing, but the result also will be much better and need less rewriting or editing.
RE: Product manual writing in a small company
I may be of assistance in your situation. What type of product manuals are you trying to produce? Where are you located? Remote location is not necessarily an obstacle, as I am quite confident that conducting a long-distance business can be done effectively with technology such as video conferencing and secure file transfer. And if a project was to require a person-to-person meeting, and there is a business case for it, then I would be open to travel to ensure the success of the project particularly where it is to the benefit of the customer, provided as I said, the business case grants it. If there is a synergy between my documentation business and what your manuals are expected to convey, perhaps we should have a conversation.
I am the Founding Director of SAMALEX Technical Services, a full-service engineering & technical documentation business concentrating in designing, creating and delivering a wide range of technical documentation. Our work includes product manuals, technical specifications, technical and scientific reports. We can also review existing work to assure technical accuracy and proper grammar usage. We provide technical translations and interpretations from English to Spanish and Spanish to English. We are located in Hamilton, Ontario, Canada. We have in our staff, an Engineer that holds dual citizenship (Canada-USA) should there be a need to have an American citizen performing and signing the work completed.
Personally, my career prior to SAMALEX, involved years in R&D, moving up to Engineering, then Marketing and eventually back to R&D running a department of 13 scientist and engineers. Along the way, crucial to our success, was the ability to convey information in a clear manner, that was of technical nature, for an international market -80% of our business was done outside Canada. Now, as an entrepreneur, my success depends on how well I can communicate what my customers is trying to sell!
We work with engineering organizations and technical business looking for Engineers and Technologists that write in an accurate and clear manner, with the ability to write that same material in technical Spanish. Please note that our engineering & technical writing is performed by licensed Engineers and Certified Engineering Technologists. I would be pleased to have a discussion on how we can serve your organization with any technical documentation requirements.
I remain at your service,
Ingrid Muschta, P.Eng.,
Director & Principal Translator
SAMALEX Technical Services
www.samalextechnical.com
Reaching clarity, through simplicity
RE: Product manual writing in a small company
RE: Product manual writing in a small company
Sorry, the candidates who come to mind must be long retired or worse.
Mike Halloran
Pembroke Pines, FL, USA
RE: Product manual writing in a small company
I have one more thought here. There are people who work full time as editors. You write the copy. The editor checks you for spelling, grammar, incorrectly placed apostrophe's,
--
JHG
RE: Product manual writing in a small company
TTFN

FAQ731-376: Eng-Tips.com Forum Policies
Need help writing a question or understanding a reply? forum1529: Translation Assistance for Engineers
RE: Product manual writing in a small company
Our tech pubs guy complains all the time that he doesn't get good initial data from most of the engineers etc. and then can't find anyone to review/redline whatever he manages to piece together.
When we got bought out by our current over lords we had to re-brand all our customer facing documentation (plus a few others) and got in some temp tech pubs folk to help get over the hump. One of them was a bit artsy - good with the Photoshopping required to re-brand images by swapping logos & changing color schemes etc. but a bit monkey see monkey do (that's more insulting than intended) on actual technical writing so limited to just the re-branding portion. The other person had a technical background and was able to be given more complex tasks or asked to incorporate significant updates/revisions etc. beyond the simple re-branding.
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?