TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>----------
>From: David Hailey[SMTP:FAHAILEY -at- WPO -dot- HASS -dot- USU -dot- EDU]
>Sent: Monday, August 26, 1996 2:04 PM
>To: Multiple recipients of list TECHWR-L
>Subject: Sanity check
>It seems to me that the primary purpose of the help file is
>to instruct, and/or inform (without splitting hairs over
>whether these are synonyms).
>BUT (excuse me for shouting) it seems to me that important
>secondary purposes include things such comforting,
>encouraging; convincing the user that the software
>developer, the software, and the user are all members on a
>highly successful team.
Dave, you raise a fascinating question. I agree with you -- and also
(to a point) with Chris Hamilton who responded to this question while I
was pondering it.
It's extremely (and primarily) important to convey the information the
user needs without obscuring it. It's also optimal if the documentation
can add to the sense that the software is pleasant to use. "Friendly"
if you will.
To achieve that, I document software in a format that is very derivative
of "information mapping" techniques. That is, my sentences are short
and to the point and I use plenty of why space. I number steps and use
unnumbered sub paragraphs for any explanation that's necessary. That's
how I "stay out of the user's way."
But I also use an informal conversational voice. Very little passive
voice, very few Latinate phrases where good ole Anglo Saxon derivatives
will work. I operate on the assumption that all my readers will have at
least a sixth grade reading level, and that few people will be offended
by text that is simple and straightforward. The point, after all, is to
get the task done and the more transparent the dox are, the faster that
will go.
Technical Consultant/ Communication Specialist
Software Services Corporation
Ann Arbor, Michigan
(800) 448-1568
*******************************************************************
My opinions do not in any way represent those of my employer.
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-
