Re: Sanity check

[Tom Neuburger <Tom_Neuburger -at- LTX-TR -dot- COM>]

Fellow writers,

Some wonderful points being made here, and lots of
issues to sort out.

Yes, tone is important, and as several people pointed out,
you can mistake which tone is right, with the best of
intentions.

The things you can't mistake when designing "comforting"
documentation (I think) are these --

1. The -important- bases should be covered clearly
and completely. All the key ideas should be explained.
This is a bigger trap than first appears, since many of
the key ideas are never discussed, since they are hidden
in the assumptions about what "everyone knows", everyone
being everyone on the development team.

I'm always comforted when writers figure out what
I really need to know, and I lose confidence in pro
forma documentation that mades no attempt to
determine where people will get lost. Like others,
I know early on whether clicking on help will help.

2. The sentences should be readable. Another big trap.
Accurate writing can be unreadable. (As an example,
the first draft of the above sentence was this cutie --
"Not all writing that says the right thing is easy to read".)
Even good writing needs editing, and editing is not easy
to learn.

3. The layout should make the page easy to scan. Misti
Delaney touched on this in her post--

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

Most readers (ourselves included) want the logic of a page
to jump out at them. We should be helping that to happen.


As to the differences between online and hardcopy, the problem
is tougher with online help. Brevity is important, and it's hard
to choose among the many things that could be said -- and time-
consuming. (Rumor has it that Woodrow Wilson, when asked to give
a two-minute speech, replied -- I will take me a week to write a
two-minute speech; I can give you a ten-minute speech on Thursday;
make it a two-hour speech and we can start right now.)

Help files are hard to do well. As a user, I encounter lots of help files
that are "helpless" -- they say the obvious and miss all the pieces
I can't figure out. I'm sure someone is helped by them, but I think
the major beneficiary must have been the development schedule.
("To ratchet the gismo, select Edit / Ratchet Gismo and click OK."
Not a word about why I would want to, or what happens when I
do.)


And none of this addresses the large marketing issues -- not the
ones that say good docs save money, but the ones that ask why
so many companies are apparently committed to bad documentation.


Anyway, my $.02 (as another subscriber is fond of saying)...
This is a good issue to ponder.

Tom Neuburger

                  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-