How to convince an organization to be proactive about an issue
How to convince an organization to be proactive about an issue
(OP)
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
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





RE: How to convince an organization to be proactive about an issue
-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: Eng-Tips.com Forum Policies http://eng-tips.com/market.cfm?
RE: How to convince an organization to be proactive about an issue
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:
What is Engineering anyway: FAQ1088-1484: In layman terms, what is "engineering"?
RE: How to convince an organization to be proactive about an issue
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
RE: How to convince an organization to be proactive about an issue
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
RE: How to convince an organization to be proactive about an issue
Hydrology, Drainage Analysis, Flood Studies, and Complex Stormwater Litigation for Atlanta and the South East - http://www.campbellcivil.com
RE: How to convince an organization to be proactive about an issue
Dan - Owner
http://www.Hi-TecDesigns.com
RE: How to convince an organization to be proactive about an issue
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.
RE: How to convince an organization to be proactive about an issue
http://www.sawstop.com/images/uploads/manuals/PCS%...
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
RE: How to convince an organization to be proactive about an issue
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.
RE: How to convince an organization to be proactive about an issue
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
RE: How to convince an organization to be proactive about an issue
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