Re: Documentation Deliverables for Complex Scenario

Subject: Re: Documentation Deliverables for Complex Scenario
From: "DWerder -at- t-online -dot- de" <DWerder -at- t-online -dot- de>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 02 Jul 2009 10:54:03 +0200

Dear Deborah,

Here are a few rough answers to your questions:

1. Training courses for users in the beginning, before using the
2. Have all the information in one large help file with a good TOC
and index
3. Access to the online help via a customizable start page
4. You could also have this start page automatically adjust to the
user's level of knowledge. This should be based on usage data, which
pages has this person already seen etc.
5. You could offer a guided tour as part of the online help, e.g. one
or more short training videos that should also be available from the
start page of the online help.
6. The topics of the help system should always offer a brief
explanation of "What is this all about? Why do I need to know this?"
before the section that actually explains how to do something.

You suggested

"Separate help systems that connect one way (Say a theoretical
help that links to the HOW to, but not the other way around)."

I think this is only an option if certain groups of users will only
need portions of the software.

In my opinion it is always good if users have the chance to see the
"big picture". If they don't want to they can still leave out the
sections they are not interested in. They should be there, though, for
those who need to know.

As to your second question,  

"For example, if the real name of the software is Business Manager,
and the upgrade portion is XY System, how do you feel about the
following text? " The XY System, or XYS, manages business statuses,
rules for achieving those statuses, and processes business activities
against these rules. XYS is not a module within Business Manager,
no XYS page or section of Business Manager that is labeled XYS.
XYS is the technology that enables business processing..."

>From a user's perspective, this information doesn't seem so relevant
to me. I would rewrite it as Geoff already suggested. A process
running in the background is only interesting to users if they
interact with it in some way.

Excuse the style of this mail, I did not have time for a proper edit.


Greetings from Germany

Doris Werder
Technical writer (member of tekom) and state-certified translator
(member of BDUE)

Doris Werder
Technical writing and translation
English>German * German> English * Spanish> German
Electronics * IT * Politics
Jahnstrasse 8
63450 Hanau
+0049 6181 160431
dwerder -at- -t-online -dot- de


Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Re: Documentation Deliverables for Complex Scenario
Next by Author: Documentation Deliverables for Complex Scenario
Previous by Thread: Re: Documentation Deliverables for Complex Scenario
Next by Thread: RE: Documentation Deliverables for Complex Scenario

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

Sponsored Ads