Documentation Deliverables for Complex Scenario?

Subject: Documentation Deliverables for Complex Scenario?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>, dvora -at- tech-challenged -dot- com
Date: Wed, 01 Jul 2009 17:23:38 -0400

Deborah Hemstreet wonders: <<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.>>

Based on this description, one obvious strategy is to design the
documentation around the structure of the software: since it is
"Internet-based", I'm assuming that this is accessed as a series of
"pages" in a Web browser. The key steps in taming this documentation
are therefore to design supportint documentation for each page:

1. Create an overview help topic based on the goals of the users (what
they want to accomplish and how the various modules of the software
let them accomplish those goals) and the tasks required to accomplish
each goal (the actual how-to steps, but at a very high level -- more
about the purpose of the modules rather than the specific buttons and
input fields). This is where you provide the overall mental model of
the parts of the software and how they interact. For example, you
might describe the financial aspects of a business in terms of
incoming money (the accounts receivable module) and outgoing money
(the accounts payable module). Note that I've described the modules
using words that the users will be familiar with.

2. Where possible, build as much of the "how to" directly into the
interface. This can be done both by rearranging the screens so that
the flow of actions proceeds logically from the top of each screen to
the bottom and from left to right (i.e., using sound forms design
principles) and by building affordances (explanations and visual or
other clues) into the interface. The more of this you do, the less
documentation you must create that will be external to the task (i.e.,
accessed in a separate window). The goal is to reduce the frequency
with which users must leave the task to consult the documentation, and
to build as much of the documentation as possible into the interface.

Note that managers and programmers may object to this approach, but
I've had great success pointing out to them that if you nail down the
interface (at least for this version) right from the start, that's the
easy part over and done with. The hard part involves making the
plumbing behind the interface work, but changing that plumbing won't
affect an interface that is designed well right from the start.
Really. Once they understand that you can complete the documentation
before the programming is finished if the interface is stabilized
early, most accept this approach based on enlightened self-interest.

3. Create separate help files for each page of the interface, just
like you'd do with the dialog boxes of other software. That's the easy

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

Much of the plumbing details (what you describe as "behind the
scenes") will be far less critical than you think. The goal is to
present only the information they really need from the perspective of
their goals and the tasks they complete along the way to those goals.
Always document so as to solve the user's problems, not to meet the
software's needs.

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

That assumption often proves to be incorrect. Alan Cooper has rather
cleverly pointed out that all of us spend more time as neophytes
(perpetual amateurs) during our interactions with a product; we are
only truly experts for the parts we use constantly. Even when we
become expert at a specific task, we lose that expertise rapidly when
we stop doing that task. Thus, make sure that the overall theory is
available everywhere: make the overview information (how the modules
interact etc.) that I described above continuously available, in all
parts of the software, then provide the necessary context to help
people quickly become experts for every task. If they don't need this
information, they won't read it. But if they do, they'll bless you and
your children when they find it. <G>

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

Never if you can avoid it. The actual physical structure of the
documentation is less relevant than what the users see: the larger and
more complicated it looks, the greater the intimidation factor and the
less likely it is that they will RTFM. So however you create the
actual documentation set, focus on providing immediate access to the
information they need for the screen they are currently seeing. This
is variously referred to as context-sensitive help or embedded help.
The nitpicky distinctions between them are irrelevant in practice;
what's important is that users see (initially) only help that is
relevant to their immediate context. But always provide links to
information for other contexts that may be relevant (e.g., links to
the help for related modules that are likely to interact with the
current module).

<<PDFs of the theory that users can access and print, and have
available whenever they want>>

Probably irrelevant. PDF is only useful for printed documentation, and
if you design the help so that it integrates with the interface (as
described above), readers should have little reason to print copies of
the help: everything they need will be staring them in the face as
they use the software, or at most one screen distant from the
interface. If they decide they need to, most can copy/paste the
desired information into Word and format it to meet their needs;
alternatively, you can provide a link to a printable version of the
current screen. This is relatively easy to do by means of CSS; I
haven't done it, but others here have and can tell you how.

<<How would you refer to this new "upgrade" and how would you suggest
relating to the two GUIs in a positive manner?>>

I wouldn't. <g> If you try to do this, all you'll be doing is drawing
attention to the deficiencies in the parts that still use the old user-
hostile interface. If you're the one who draws the short straw and has
to explain this, treat it as a "road map for the future" kind of
challenge: "We know that modules X, Y, and Z suck, but look at the
great new interface for modules A, B, and C. We promise that as soon
as possible, we'll make modules X, Y, and Z as good as A, B, and
C." (You might want to express that more diplomatically. <g>)

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

First off, never create an acronym or initialism to eliminate a single
simple word such as "system", and never use "or" to describe a
synonym. Users hate them, and the more you create, the harder it
becomes to focus on what they're actually trying to understand. Here,
you're describing plumbing that is irrelevant to the reader; focus on
what they see and how they use it. If there is no XYS page, why
describe it? You'll only confuse everyone. Also, I have no idea what
statuses are or how you achieve them. You'll need to rephrase those
concepts using real words that real people will understand.
Speculating wildly, here's one possibility:

"To run your business using Business Manager, you must be able to
manage all your business activities. Business Manager lets you
describe each business activity through a series of rules and the
processes that you will use to follow those rules. Here's how:
- First, define an activity [description and link].
- Next, define the rules that control that activity [description and
- Last but not least, define the processes governed by those rules
[description and link]."

Geoff Hart (
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
Effective Onscreen Editing:


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: Edit PDF in Acrobat Pro?
Next by Author: Best Practices in Context-Sensitive Online Help?
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