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.
Subject:Which kind of ransom note? From:mlist -at- safenet-inc -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 30 Jun 2005 11:04:01 -0400
WebHelp system (done in RoboHelp X5).
It's help for a networked security appliance.
There's a command-line interface for the appliance (via ssh or via local
console).
There's a command-line interface for client computers (which in some
procedures must perform actions in conjunction with the appliance).
There's a handheld PIN Entry Device (PED) that plugs into the front of the
appliance when you need to authenticate to it. That device has a 4-line X
20-character LCD and a numeric keypad with "YES" "NO" "ENT" buttons, and it
accepts little key-like tokens (three different kinds).
When, for example, I'm describing the initialization of the hardware
security module (HSM) within the appliance, I have to describe a
command-line dialog with the appliance, and a keypad-and-LCD dialog with the
PED, plus some physical actions. I differentiate between the two
conversations (on my Help pages) by showing the CLI portions in black
courier, and the PED portions in red someotherfont. This, of course, is
interspersed with the regular text on the page (expository/explanatory) and
punctuated with the occasional Note or Caution, which are offset by
appropriate icons.
Almost every step has options that must be considered, and implications from
the resultant choices that have effects in later steps.
At the moment, my solution is to highlight a likely word in a step or a
dialog and embed some DHTML drop-down text at the spot. The advantage is
that the explanations are invisible unless you need/want them, but the
color/font of the highlighted word (or phrase) lets you know it's there.
The disadvantage is that the highlighting needs to stand out, so it's
different than other text elements.
Taken all together, some of my procedural Help pages have a very
ransom-note-ish look to them.
I can ease it a bit by splitting longer sequence pages into multiple pages,
but do we really want ten separate pages for a ten-step procedure (that has
a timeout)?
Instead of dropdown text, I could just link to a separate page with the
explanations and implications, but that would do little to ease the
ransom-note look in the main flow. Links do need to stand out from ordinary
text, after all.
I've seen cleaner-looking pages that didn't have font-and-size-and-color
changes, but then it was less obvious that different pieces of text had
different importance or applicability. For example the action of a step
would be lost in the pre-amble and post-amble of that step, all of it in the
same font and color and looking very elegant, I'm sure...
What are some approaches you other folks use to avoid the
clown-barf/ransom-note look without losing usefulness?
Kevin
--
The information contained in this electronic mail transmission may be
privileged and confidential, and therefore, protected from disclosure. If
you have received this communication in error, please notify us immediately
by replying to this message, and then delete it from your computer without
copying or disclosing it.
The information contained in this electronic mail transmission may be privileged and confidential, and therefore, protected from disclosure. If you have received this communication in error, please notify us immediately by replying to this message and deleting it from your computer without copying or disclosing it.
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
