Product manual writing in a small company 3

[geesamand]

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

 

[drawoh]

geesamand,

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

 

[tomwalz]

Generally I write them. As a guide I use the concept that they should be readily understood by anyone reasonably skilled in the practice.

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.

http://www.carbideprocessors.com

Good engineering starts with a Grainger Catalog.

 

[MintJulep]

Generally speaking, engineers are crappy writers. We know how things should happen and how things should work, so we tend to leave out important steps and instructions.

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.

 

[geesamand]

I had been noodling on hiring a technical writer or contracting one to be a consultant. But they would have to have industry-appropriate experience and help us address the big questions. I do not see how it would be appropriate to give them the task and leave them to work in a vacuum, even if they were a full-time hire with significant experience.

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

 

[romke]

the appropriate reading style will depend on the product and on the customer who will buy it. generally speaking style should not be unnecessary popular - you are writing instructions and not a "article that has to sell". clear, precise and as comprehensive as needed instruction is what is called for, not literature that fascinates the reader.

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.

 

[ingridmuschta]

Dear Geesamand,

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

http://www.samalextechnical.com

Reaching clarity, through simplicity

 

[tbuelna]

I would agree with MintJulep, engineers are definitely no the best choice for writing tech manuals. Most of the tech writers I have worked with were excellent at their job. But they always spent time working with me when they wrote the manuals for the hardware I designed.

 

[MikeHalloran]

I think you need to hire an experienced technical communications manager (I'm not sure of the title), whose first task will be to construct a Style Guide, and whose next task will be to contract for or hire technical writers to follow the Style Guide while writing your manuals.


Sorry, the candidates who come to mind must be long retired or worse.


Mike Halloran
Pembroke Pines, FL, USA

 

[drawoh]

geesamand,

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, , and general readability. You get the facts straight. The editor makes it accessible. You stay off the editors group on Facebook so that you don't find out what they are saying about you behind your back.

--
JHG

 

[IRstuff]

Just one caveat about copywriters; some are very fascist about grammar "rules." Make sure you read each and every line to ensure they didn't much up your intent because of run-on sentences and the like.

TTFN
faq731-376

Need help writing a question or understanding a reply? forum1529

 

[KENAT]

Yep, I've had portions of internal procedures re-written by a senior director to be more grammatically correct, but contextually completely wrong.

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.

Posting guidelines faq731-376

http://eng-tips.com/market.cfm?

(probably not aimed specifically at you)
What is Engineering anyway: faq1088-1484​