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.
Tony Markos wonders: <<how do you define user-friendly
[documentation]?>>
User-friendly documentation accomodates the way I think. This means
that, among other things:
It is organized to match my understanding of how the software works,
and provides enough context for me to create that understanding where I
formerly lacked it. This lets me find information quickly by following
a logical path through the hierarchy, or by learning what path I should
be following, without ever (or only rarely) leaving me fearful that I'm
following the wrong path to a dead end many pages or links deep in a
mysterious structure.
The documentation matches the product closely, so that as soon as I see
part of the interface, I immediately know what to look up in the
documentation. For software, this may mean that I provide a separate
index for every dialog box name so that users can look up that name in
the manual. For hardware, this may mean that I provide an initial
photographic index in which all the key components are labeled clearly,
with an index entry for each and possibly even page references directly
in the photographs.
The docs provide a good index with appropriate keywords. If they're
online docs, that means I'm not forced to rely on a primitive search
function or a random walk through the contents to find what I'm
seeking. If there is a search function, it is moderately intelligent;
that is, it understands stemming (e.g., for the concept of writing,
typing the "writing" keyword would find "written", "to write", "wrote",
etc.), "sounds like" (for those times when I don't know how the jargon
is spelled), and "related concepts" (e.g., if I'm searching for
foreign-language characters, the search will be smart enough to turn up
links to Unicode fonts too).
The documentation is concise--which means that it provides information
economically. It emphatically not mean that the writing is terse and
telegraphic or that it omits useful information in the interest of
appearing short. The instructions and explanations use the same
language as the software, but provide synonyms where it's likely that I
may be using a different "industry standard" jargon than the software
uses.
Graphics are used to communicate things that prove the old maxim that
"a picture is worth 1000 words", but not simply to add color to the
screen or page.
The visual hierarchy of the page or screen uses white space
intelligently, and supports hierarchical organization of the
information. For example, brief instructions for experts are clearly
separated from detailed instructions for amateurs so that both are
available, depending on my needs, but are not so densely intermingled
that it's hard to choose one or the other.
The documentation is comprehensive, which means that it is written with
a clear understanding of all the things I need to accomplish with the
product, including how to work around the product's known flaws, when
to use one alternative instead of another, and where to turn for
additional help. For example, with Web-authoring software, I want to
see a URL (a hyperlink for online information) for the W3C tag
reference so I can look up anything that isn't included in the
documentation.
Of course, one person's meat is another person's vegan nightmare. <g>
All these things will help make documentation better for most people,
but still won't meet unique needs or provide the perfect solution for
everyone.
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
---
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.
