Documentation Deliverables for Complex Scenario

Subject: Documentation Deliverables for Complex Scenario
From: Deborah Hemstreet <dvora -at- tech-challenged -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 01 Jul 2009 16:34:00 -0400

Hi all,

I am hoping that my question will bring about a LOT of discussion. I am
looking for thoughts about documentation deliverables and usability for
a very specific scenario. Any and all thoughts and input about how
things COULD be handled, out of the box thinking, etc. would be greatly

My client has a very complex Internet based software (SW) that is used
by organizations to manage a major aspect of their business processes.
To date, the only documentation provided to clients was marketing
literature and the online Help. The online Help was poorly written, and
more "how to" oriented - however, it did little to help users navigate
the complexities of the SW which has modules that feed each other, and a
variety of other issues.

The client is preparing a major upgrade of their SW which is essentially
rewriting a portion of the SW that will impact 95% of the functionality
(more user-friendly, more customizable to specific organization needs,
etc.). The GUI, however, will only be impacted partially. Half of the SW
will have the current GUI, half the old GUI. (The extent of the SW is
such that there is no way everything can be rewritten all at once - this
is a business decision that cannot be changed, so let's not discuss that
its a bad idea, we all know it is....).

To date, clients have never received a lot of information about the
theory of the SW they use, and what the SW does behind the scenes.
However, this information is critical if the users are to make the
correct decisions when using the SW to meet their organization's needs.

Given that CD or printed documentation is NOT an option, and given that
SOME of the theory is important all of the time, but most of it
important only in the first 6 months of use of the SW, after that, they
will know the important stuff and only need HOW to do something (not the
why behind it), HERE ARE MY QUESTIONS:

1. How would you recommend handling the documentation?
a. One large help file, users would have to use the Contents, and
wade through info in the Index or in a search to find the info they need
b. Separate help systems that connect one way (Say a theoretical
help that links to the HOW to, but not the other way around).
c. PDFs of the theory that users can access and print, and have
available whenever they want
d. Something else I've not thought of?

2. How would you refer to this new "upgrade" and how would you suggest
relating to the two GUIs in a positive manner?
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, the
rules for achieving those statuses, and processes business activities
against these rules. XYS is not a module within Business Manager, there
no XYS page or section of Business Manager that is labeled XYS. Rather,
XYS is the technology that enables business processing..."

I am extremely concerned about designing the documentation in a manner
that is a user-friendly as possible. So any and all thoughts on this
would be greatly appreciated. As you can see, there are a lot of
limitations. Since I work by myself, I don't have the advantage of being
able to discuss the pluses and minuses of different options with others.

I hope that a lively discussion on this will be beneficially to myself
and others out there.



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: Online Help Headings Question
Next by Author: Re: Documentation Deliverables for Complex Scenario
Previous by Thread: Re: Edit PDF in Acrobat Pro?
Next by Thread: Re: Documentation Deliverables for Complex Scenario

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

Sponsored Ads