Re: our recent discussion of proofing, required technical skills, and writing in general

[Alexia Prendergast <alexiap -at- SEAGATESOFTWARE -dot- COM>]

Re: our recent discussion of proofing, required technical skills,
and writing in general...

>"A beginning technical writer I worked with at a software company
>demonstrated
>his lack of understanding of C. He replaced all the semicolons with colons in
>the example code throughout a 1200-page programming manual. He said the
>semicolons were not grammatically correct."

>From an email titled: winners of the "Worst Technical Writing" contest

I'll subtitle the stuff below "reasons to proof your docs"

Alexia
--
Alexia Prendergast
Senior Technical Writer
Seagate Software
alexiap -at- sems -dot- com
>
>"Type the field name Name in the Field Name field."
>
>"Warning! The Unauthorized Misusage of Data is Prohibited"
>
>"Before unscrewing, remove four foot rubbers."
>
>"Since the user interface for analyzer calibration refers to calibration as
>"calibration," this chapter will refer to the process of calibration as
>calibration."
>
>While viewing a video regarding the use of a well-known Windows word
>processing program, one of the topics was to ensure that you "Proof-Read"
>your work. The screen of the video, however, displayed the following:
>
>     "How To Prof"
>
>"5.5.13 Writing Style
>In general, the active voice is used in all procedures. References made in
>the textual portions will be identified by Title and procedure document
>number."
>
>A company that does training seminars sent a brochure for the following
>seminar:
>
>     "EMPLOYMENT LAW FOR NON-HUMAN RESOURCE MANAGERS"
>
>     (Shades of Catbert, the evil director of human resources, eh?)
>
>
>"10. Do not allow anything to rest on the power cord. Do not locate this
>monitor where the cord will be abused by persons working on it."
>
>This comes from a technical publication written for the British military.
>     "It is necessary for technical reasons that these warheads should be
>stored with the top at the bottom and the bottom at the top. In order that
>there
>may be no doubt as to which is the top and which is the bottom, for storage
>purposes it will be seen that the bottom of each head has been labeled with
>the
>word TOP."
>
>
>This little gem is from the "Human Factors Requirements" section of a
>design document I reviewed while developing a documentation plan for a
>high-tech
>product about eight years ago:
>     "The pushbutton must have a tactile feel to the user when depressed."
>(I fear the Human Factors Engineer was taking his job too seriously.)
>
>"ASSEMBLY OF 886a (Left rear tire) to 456b (rear axle):
>Proper gobulation is needed to do it like this (see diagram). If it doesn't
>want
>to gobulate, use a brush tool to cut off plastic tip of part 886a or inner
>core
>of part 456b.
>Insert the insertables and re-gobulate if former gobulating components have
>discongobulated.  After a few mintes, try to spin part 456b by spinning it.
>Move
>to next step before moving."
>
>From the owner's manual of a smoke detector.
>"In case of fire, arouse all occupants and leave the building."
>Arouse them? Is there time? More importantly, if the house is on fire,
>who is in the mood?
>
>"...The Computer...
>     If you turn on the computer and nothing happens, please go to another
>book. If your computer stuffs up and it isn't one of the following problems,
>it
>is uncureable!
>Disconection: Disconection may be because of the actual program. Sound
>problems:May result to speakers."

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html