RE: doc'ing the docs

Subject: RE: doc'ing the docs
From: "Sean Brierley" <sbri -at- haestad -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 3 Dec 2002 13:18:24 -0500


What makes you think the reader has to have mastered the help before
reading the topic?

This might seem like a silly question, but the help is immediately
available from the startup, from the Help menu, there is a topic called
"Using the online help" and in the printed book that accompanies the
software, there is the same topic.

One reason for including this information is that engineers with a
masters degree and who are used to working in a software environment
were unable to figure it out on their own. Granted, it's a show/hide
button and a couple of other things, but in this case the target
audience is other engineers, so those who missed the boat are
representative of the audience.

Certainly, this doesn't complicate a 1200+ topic help system. And, it
doesn't make the help seem harder to use--unless you think that it is
bad to supply any documentation because the presence of documentation
makes everything automatically seem harder to use. Agreed, CYA is
self-serving, but of the bunch it's the only self-serving reason and
does not interfere with the rest.

Cheers,

Sean

-----Original Message-----
From: Gordon Meyer [mailto:gordonmeyer -at- mac -dot- com]
Sent: Tuesday, December 03, 2002 11:30 AM
To: TECHWR-L
Subject: Re: doc'ing the docs



I find these rationales for including "help on help" to be revealing:

- It's a CYA
- Reviewers/QA won't bother me if I include it
- Tech Support won't complain if I include it
- It's only 4 (!) pages

In my opinion, the negative impact of including it outweighs these
benefits. It complicates the help system, it makes using the help seem
harder, and most of the time it ignores the fact that in order for a
user to find and read the content, they've already mastered the very
steps being described. That's insulting at worst, silly at best. I
think the impression it gives is that the author didn't even consider
how the information would be used or accessed -- it was just thrown
into the pile for self-serving reasons (see above).

But I'd love to be convinced otherwise. If you have a really good "help
on help" section that you've written, would you be willing to share a
copy with me? It will become part of an article I'm writing and will be
used with full attribution, if you desire.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Previous by Author: RE: Frame Maker Book file-Query!
Next by Author: RE: doc'ing the docs
Previous by Thread: RE: doc'ing the docs
Next by Thread: RE: doc'ing the docs


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


Sponsored Ads