How to convince an organization to be proactive about an issue 3

[geesamand]

So as with many small companies, our product documentation is not viewed as a feature of the product. It's written by the (unfortunate) person who knows the most about the product about a month before the documentation is needed to support shipments. They're not awful, but they could be a lot better. Customers don't particularly complain about it and we haven't been burned yet by any lawsuits based on poor instructions, so there's no special impulse to drive change. Then the maintenance of the documentation gets dumped on my department and there is not much to guide us in writing it appropriately, nor tools to make it manageable. To the company, we're just competent enough for the organization to be satisfied with it.

My company values the reduction of risk. I believe that less-than-world-class documentation is a source of risk, and that hiring or contracting a competent technical writer will help immensely. We're used to reacting to mistakes and justifying the change by the cost of the mistake that initiated the mistake. This can lead to disjointed systems or layers of band-aids - like building a castle, one wall at a time, after each battle. How might I propose change in a way that builds a proper castle on the first try?

David

 

[GregLocock]

Various random ideas

-commission a survey that suggests your product's documenation is not as good as the competition
-get the costs your support people incur because of poor documentation
-slightly off topic, my wife was amazed that a 45000 dollar SUV's handbook came in a crappy thin pvc cover rather than a proper leather one. bear in mind a complete service history is essential for selling a car , why isn't the cover robust and attractive?

Sorry I'm lousy at brainstorming

Cheers

Greg Locock


New here? Try reading these, they might help FAQ731-376

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

 

[KENAT]

Unless the user is directly paying for it, manual is safety critical material or you're in the mass consumer industry where they take these things more seriously etc., 'user manuals' or equivalent don't always seem to get the love they arguably deserve.

First there is the fight over who owns it, design engineering who designed the product and presumably know how it's supposed to work, development testing & applications engineers who presumably know how it really works from customer point of view, service/tech support whose role it is directly supporting, marketing because it's customer facing...

Second, no matter which group it ends up under it may not be considered 'core competency' and be given a correspondingly low priority (e.g. while our overall staffing is back up to more than half of its per-recession level our tech pubs is at around 1/4 of per-recession levels or something like 1/6 of historical highs - and it's not all just advances in tech pubs SW tools etc.).

Fundamentally improvements probably need to be justified by some kind of ROI. In your case the ROI isn't so much in increased revenue from more sales but in reducing costs by various means e.g. less time spent on tech support, less warranty repairs, less (potential) law suits... Sadly these are all difficult to quantify, and the latter may include some 'black swan' aspects.

Thoughts on outsourcing tech pubs:

[ol 1]
[li]Your engineering will still need to provide most of the content since outsourced vendor probably won't have the level of product familiarity (or even fundamental technical expertize) to prepare this.[/li]
[li]A good tech author should be able to edit the content some, but without product familiarity or at least relevant technical skills they may tend to introduce technical errors so may require several review cycles of the documents.[/li]
[li]Even a moderate tech author should be able to help with the all important but oft neglected formatting. However unless you plan on always using the same external author (will they always be available when you need them?) you may need to put some effort into coming up with your 'style guide'.[/li]
[li]Depending on type of product you may want your tech author to be good with graphic tools for creating images &/or perhaps be a competant photographer...[/li]
[/ol]

Posting guidelines faq731-376

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

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

 

[MikeHalloran]

Good points made by KENAT.
Expanding on one, it might be a good idea to find a senior/ retired technical writer to compose a style guide before putting much effort into the actual manuals.

At least try to find an example of some company's style guide so you understand what that means, and can use it as an example when you take a crack at writing a manual yourself. I don't have an example to provide; they're not generally defended with armed force, they just aren't widely disseminated.



Mike Halloran
Pembroke Pines, FL, USA

 

[drawoh]

geesamand,

There is an important difference between a technical writer and a designer/engineer. As the technical writer, you tell the user to put the pickup truck on the hoist, lift it up and remove the front suspension. Remove the engine bolts. Lower the truck. Lift out the engine, and replace the spark plugs.

As the designer/engineer, you write the manual telling the user just to replace the spark plugs, and then you make sure the plugs are accessible.

I have been told that with software, a good design strategy is to write the manual first, then write the code.

--
JHG

 

[beej67]

Start posting these around your workplace until someone gets the picture..

Hydrology, Drainage Analysis, Flood Studies, and Complex Stormwater Litigation for Atlanta and the South East -

http://www.campbellcivil.com

 

[MacGyverS2000]

That would be funny, beej, if it wasn't so true. The "user manual" translations for many of the Chinese lasers I've seen range from barely legible to "is that even a language?" One a scale of 1-10, with 10 being the former and 1 being the latter... I'd give your solder station instructions a 7. They get the point across, but the flowery language leaves something to be desired. It's once you get below a 5 that things get interesting.

Dan - Owner

http://www.Hi-TecDesigns.com

 

[geesamand]

"There is an important difference between a technical writer and a designer/engineer. As the technical writer, you tell the user to put the pickup truck on the hoist, lift it up and remove the front suspension.

Remove the engine bolts. Lower the truck. Lift out the engine, and replace the spark plugs.
As the designer/engineer, you write the manual telling the user just to replace the spark plugs, and then you make sure the plugs are accessible.

I have been told that with software, a good design strategy is to write the manual first, then write the code"

We have a product like that. It involves a procedure to change a maintenance item. The competitors design has a procedure to set up for the maintenance that's only three steps, but it's not a durable condition for extended periods of time and sometimes it doesn't work and requires an alternate procedure. We designed our product to set up for this maintenance in a robust and reliable way but as a result the set-up involves more steps. Feedback from a few customers was "the manual procedure is too long - shorten it" (subtitled: "...so that our untrained and minimally skilled technicians can do it half asleep in the night without supervision") and handed it to the technical writers. Or replace words with pictures. Everyone nodded in agreement and pushed the tech writers to start cutting down. The tech writer had to explain that the written procedure is tied to the mechanical procedure, and neither can be shortened unless the entire product is redesigned. Upon further review, the written procedure was revised for clarity and it did not get shorter.

I'm sure this is far from unique. I've been around long enough to understand that a long manual that is accurate and detailed is vastly better than a short manual that lacks information. But to an outsider, the short manual makes the product that is easier to use.

 

[MacGyverS2000]

If anyone would like an example of a quality manual, take a look at the User Manual for a SawStop machine:

http://www.sawstop.com/images/uploads/manuals/PCS Owners Manual Model PCS31230 V5.0 09-13.pdf

Plenty of clear, well-labeled pictures and diagrams, good text, etc. 123 pages, mind you, but I'll take verboseness over unclear succinctness any day... nothing like a 25-page "instruction" manual that says "build and install the engine" as a single step and provides you with a box of loose parts.

Ikea instructions are relatively clear using nothing but pics... I've been flumoxed once or twice because a specific detail was not drawn, but it's generally a 50/50 shot in those cases.

Dan - Owner

http://www.Hi-TecDesigns.com

 

[geesamand]

The Ikea example was brought up as a possible reference for improvement. "Make it easy like an Ikea manual". Again, it's easy to say.

The Ikea documentation model is not for everyone / everything though. Ikea does graphical because they were spending so much money and development time handling the wide range of languages. They do it to improve speed to market and reduce translation costs, not because the graphical manuals are considered to be better. First, the products are designed with this method of documentation in mind. Second, their products are generally very simple structures with fairly limited liability. Third, they have assembly services for those who don't want to assemble it themselves, and customers are flexible about when the assembly takes place. Fourth, their price point is low and the expectations of consumers are pretty low. Most consumers just return the item or throw it away if the quality or documentation is junk.

For industrial machinery these four things are basically the opposite end of the spectrum.

 

[MacGyverS2000]

I'm not suggesting Ikea-style manuals are what you need, but they are a high-quality, easy-to-follow set of instructions that anyone with a high-school degree (and plenty without) can follow. You don't need to follow their lead, but whatever instructions you provide should be clear and to the point. Reading unnecessary text wears a user down, but don't remove more than the minimum necessary. The SawStop manual is possibly closer to what you're after.

A good writer will choose between pictures and text when one or the other provides more information (or both, when appropriate). Try describing tieing your shoelaces over the phone... now show pictures... finally, show a video. The video will be the best of the three, but it can be even better when narrated.

Dan - Owner

http://www.Hi-TecDesigns.com

 

[lacajun]

I know a very good technical writer looking for work, if you can sell your organization on the importance of documentation.

I missed sales because my manufacturer had not updated its documentation since 1992, while its competitors had updated its documentation in 2012. He knew that my manufacturer was not updating the product because it was not updating its manuals. They paid $2000 more for the competitor's equipment.

Pamela K. Quillin, P.E.
Quillin Engineering, LLC