TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>How do you handle this when you hit optional stuff?
>Material that the user/administrator could CHOOSE to do/not-do or
do-one->way/do-another-way...
>We also have product variants that are pre-set in the factory, and
which >then affect how many things are done.
For optional stuff, I either include it as a tip or have an expandable
section. Whether I use or tip or expandable section depends on the
weight of the alternative. Meaning, if the alternative is of "the road
less traveled," I would include it as a tip (featuring my own pretty
"tip" icon). For example, "To eliminate flying monkeys en masse, simply
pour water upon the Wicked Witch of the West. Tip: if you'd rather
dispatch flying monkeys one at a time, you can do so using the aluminum
baseball bat bundled with your product."
When an alternatives are equally viable and possibly desirable, I use
expandable text. For example, "There are three ways to prevent Little
Bunny Foo Foo from bonking field mice on the head: Way 1: Appeal to his
better nature; Way 2: Threaten to turn him into a goat; Way 3: Show him
your grandmother's recipe for Hasenpfeffer. Choose the option you prefer
below." Of course, it would all be nicely formatted and bulleted.
For variants that are pre-set at the factory, I'd have to build new
pages. In these pages, I would, of course, reuse as much content as
possible.
For "multiple 'browse sequences' that might involve the same page for
several user approaches, while other pages might be unique to just
one-or-another browse sequence," I probably use the same technique you
use in Flare. If we are talking a few pages, I have them folded into one
"story" and use page level conditional tags to define what gets built
where. Where I have several unique pages that compose an entirely unique
workflow, I have several "stories" and use conditional tags to build
each.
Leonard
-----Original Message-----
From: McLauchlan, Kevin [mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com]
Sent: Monday, May 10, 2010 1:08 PM
To: Leonard C. Porrello; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Context-sensitive - menu-item topic or... Clippy?
Leonard C. Porrello [mailto:Leonard -dot- Porrello -at- SoleraTec -dot- com] said
a bunch of good stuff, including:
>
> I've created my documentation to meet the needs of several types of
> users: those who want and in-depth understanding of the entire product
> workflow; those who want to understand the workflow for just
> part of the
> product; those that want to understand just a particular
> field, term, or
> concept; and those who aren't sure what exactly they need to know but
> who are looking at a GUI and wondering WTF?
>
> Our product comprises several tabbed GUIs, each responsible for some
> part of the Information Lifecycle Management (ILM) process and
> infrastructure. For example, one GUI defines storage vaults and media;
> another defines data ingest polices; and another defines data movement
> policies. To create an ILM system from scratch, the user would use
> several different GUIs in pretty much a pre-defined order. Later, to
> expand or modify his system, the user would employ individual GUIs as
> needed. For example, if the user wanted to tweak just his data ingest
> policies, he would use just the GUI dedicated to creating and managing
> data ingest policies.
We have a little of that on a smaller scale, since
we're dealing with a hardware product and the installation,
configuration, ongoing maintenance and occasional
adaptation of that hardware and our software that
goes with it.
Just reading what you have to say here gives me a nudge
to go back and review some of my organization and
bridging.
> Within each GUI, we provide hover help and three additional help
> options: "Table of Contents," "Overview," and "Current Page."
> All three
> link to the same browser based on-line help (but in different ways).
> "Table of Contents" links to the overview of the entire ILM workflow
> with which the documentation begins. "Overview" links to the overview
> section for the given GUI the user has open. This section includes an
> overview of the workflow for the given GUI, how the GUI fits into the
> overall product workflow, and links to specific help pages for
> individual GUI tabs. "Current page" links to the page in the help that
> documents the GUI tab the user is currently using. Each help page
> includes an overview of what a user can do and why, in relation to
> overall workflow, they'd want to do it.
That's certainly clear-cut when the steps are straightforward
and follow from previous actions.
How do you handle this when you hit optional stuff?
Material that the user/administrator could CHOOSE
to do/not-do or do-one-way/do-another-way...
We also have product variants that are pre-set in the factory,
and which then affect how many things are done.
In the case of - say - authentication and some related
procedures that come up frequently, I've been a little
un-even. In some cases, I make a split at the page/topic
or section-of-ToC level - one branch for doing it one way
if you bought that configuration, the other branch if
you bought a different configuration, and then those
branches (multiple topic-pages) either just stop at
the end of each, or lead to a common "next" step where
a) there is a particular next step and
b) it has more common elements than not, thus justifying
the re-merge of the 'narrative'.
In other cases, I've made the split "on-page" by using
drop-down or expanding text.
By "un-even" I mean that I didn't have a hard-and-fast
rule for when it made sense to simply offer a couple
of optional paths within a topic page and when it made
most sense to break out entire branches of topic sequences.
> I've structured the help so that the user can understand workflow and
> work through tasks by simply reading the TOC from top to
> bottom. Section
> titles also include GUI names so that a user can browse to the section
> for any GUI without needing a clear idea of the task they
> might want to
> accomplish with that GUI.
>
> In short, the help is task centric AND application centric. Along with
> documentation for particular GUIs, tabs, and fields, it features an
> abundance of overview and in-depth information for users who want to
> understand the big picture. It also includes terse "How To" sections,
> for users who want to be led through a task as quickly and
> painlessly as
> possible, as well as tutorials. And of course, the help also features
> search functionality and an index.
Do you have, say, multiple "browse sequences" that might involve
the same page for several user approaches, while other pages might
be unique to just one-or-another browse sequence? I'm using that
term because I'm familiar with it from RH and Flare - not sure if
it's how the concept is named in Author-It, Doc2Help and other HATS...
I was going to ask about conditions here, but I think that'll
be too much. I'll start a different thread on that.
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
