Re: Sanity check

Subject: Re: Sanity check
From: Misti Delaney <mdelaney -at- SOFTWARE-SERVICES -dot- COM>
Date: Mon, 26 Aug 1996 14:50:45 -0400

>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.

Misti Delaney (Tucker)

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-

Previous by Author: An interesting design problem
Next by Author: Tips Help
Previous by Thread: Re: Sanity check
Next by Thread: Re: Sanity check

What this post helpful? Share it with friends and colleagues:

Sponsored Ads