Tuesday, June 17, 2014

Documentation Blues...

The whole story would require writing a book, but one element of it I touched on while explaining to a friend why the information is often slightly wrong (or missing) and the English is oftentimes a bit unnatural in hardware manufacturer press releases.  Following is a (slightly) modified version of what I wrote to my friend:

About that new device - I've been looking around on-line, and I've noticed a lot of Internet pages that all seem to be based on one press release from XYZ.  It's a fascinating piece of equipment and should be useful.  Regarding the fuzzy and confusing text on-line about it, I would say (based on the time I spent in the documentation department of a manufacturer), that this company has the same issues I saw at ABC.  To detail the process:

1) New product development is conducted under tight security, with little or no information shared outside of the R&D department.

2) Once each new product gets a green light to proceed, the marketing department gets some vague information regarding features, but little or no technical details.

3) At a certain point, the marketing department has to develop a marketing strategy, so they are provided with a little more information, and they begin to put together/write some presentation type material - based on very sketchy technical details.

4) Meanwhile, in another department, the operating instructions began to be written by people who have never actually touched (or even seen) the product, or sometimes based on a very early prototype model.  Since the writers can't actually use the equipment or can only (if they're lucky) briefly try out an early prototype model (which invariably is quite different from the final production model), they don't understand the machine very well, and it's nearly impossible to avoid some mistakes.

5) The service and technical manuals begin to be written based on specifications from the marketing department(!), operational information from the (error-prone) user manuals, and minimal information from the technical people (who are under strict orders to protect any sensitive technical information to prevent it from getting into the hands of competitors).  As a result, the service manuals have many additional errors (some of which are later fixed post-production thanks to feedback from the field technicians who must service the equipment and need a certain amount of accurate information).

6) And one or two steps behind most of the above steps are translations of the original text into other languages.  So the defects in the original information (brought on due to the company's need to protect itself from industrial espionage) are amplified through translation shifts (which are nearly impossible to avoid) and (typically) lack of technical knowledge by the writers.

Well... there's more, but the point is that there is - from the very first stage - a kind of balancing act between the company needing to protect itself from industrial espionage, but also needing to promote its products and to provide enough (but not more) information to get customers to buy the product.

Lots of background, but I think it's important, as - in reading over the XYZ product text - I can see several issues that appear to be based on the typical scenario I've described above....

LHS - Tokyo

1 comment:

diego.a said...

Dear XYZ,

I've noticed you would like to share info. w/ your customers, but not your competitors. Your current process confuses both customers and competitors. I have the perfect solution:

1) Rent a private island.
2) Fill it with enough food for the duration of R&D.
3) Put me on said island for the duration of R&D.
4) Air drop the product and writing tools.
5) Air lift all the wonderfully clear and precise documentation I have written right before your PR blitz.

I am not married and I hate my dumb, wiener kids.* Therefore, I will not miss the trappings of modern-day suburbia. I will have no contact with the outside world, preventing me from selling your precious secrets to you competitors. It's win-win for everyone!


* Just kidding. I have no kids.