Re: Documentation Deliverables for Complex Scenario

Subject: Re: Documentation Deliverables for Complex Scenario
From: Kathleen MacDowell <kathleen -at- writefortheuser -dot- com>
To: dvora -at- tech-challenged -dot- com
Date: Wed, 1 Jul 2009 16:35:23 -0500

Hi Deborah,

What I'd suggest would be two indexes or TOCs, if you will. One a simple
topic list, another organized by how-tos. Not knowing how you're presenting
this and what software you're using, I'd guess that at least you could merge
the topics for Business Manager with the new content. I see the setup for
the How To topics like this:

How to Start x (e.g., a Project)
How to End x
How to ...

Then, make each How to a complete module, beginning with a short statement
of how many steps are involved, a list of background info necessary with a
link to it, and links to each step in the process. This would avoid one of
my pet peeves with help, which is the unending loops, without being able to
really tie it all together. Also provide enough information in each step so
that it is a complete topic; this way people will be able to quickly learn
about/remember the processes.

Once people have gone through the steps enough times (6 mos), they'll be
able to access a step if they need a reminder, and they'll also be able to
use the index to look up a specific topic.

I'd also be sure to label or organize all the content according to what
aspect of the software it references (e.g., Business or XYS). Somehow do the
same with the steps, so that the index doesn't just show up with a list of
step 1, step 2, etc. (which I have seen, believe it or not).

Peter's comments aside (and he's brilliant as usual), I'm not sure I see a
problem with the way things are being done, so long as they work well
(always the kicker). Considering that people already have to learn a new
system, at least they'll have something familiar too.

I know Peter was being snide, but some of what he said actually sounded
reasonable as an explanation.

Very interesting question (and project :-)

Good luck


On Wed, Jul 1, 2009 at 3:34 PM, Deborah Hemstreet <dvora -at- tech-challenged -dot- com
> wrote:

> 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
> appreciated.
> 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.
> Thanks!
> Deborah
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Kathleen MacDowell
kathleen -at- writefortheuser -dot- com
kathleen -dot- eamd -at- gmail -dot- com

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:

Documentation Deliverables for Complex Scenario: From: Deborah Hemstreet

Previous by Author: RE: Absence of FrameMaker from your skill set -- what does it say?
Next by Author: Re: Interesting use of infographics for a resume
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