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:Re: A reminder: visual and other indexes From:Mike Starr <mike -at- writestarr -dot- com> To:'techwr-l List' <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Sat, 09 May 2009 10:50:21 -0500
This brings to mind my firm belief that complete documentation contains reference documentation despite current received wisdom that we should provide only procedural documentation.
Assuming I'm allowed to, I'll always provide chapters that describe the menus, toolbars, workspaces and dialog boxes. This also provides all of the content I need for single-sourcing context-sensitive help.
I maintain that the average user will seek the required information in their preferred format (print, PDF or online help) and if they don't find it there, they'll contact tech support (via phone, live chat or email... thus increasing support costs) rather than checking other documentation formats first.
--
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Technical Illustrator
Graphic Designer - Desktop Publisher - MS Office Expert
(262) 694-1028 - mike -at- writestarr -dot- com - http://www.writestarr.com
Geoff Hart wrote:
> In another discussion group, someone reported a problem with a visual
> indicator that suddenly appeared in her Word documents. Turns out it
> was Word helpfully applying a paragraph border, probably because of
> its "autoformat as you type" function. What's relevant to techwr-l was
> her response, namely that Word's help wasn't helpful because she
> didn't know what search terms to use. This provides a twofold reminder:
>
> First, search tools are only useful if the user knows your top-secret
> code words for a given concept. If not, they're SOL. So the first
> reminder is that you should index your documents using the specific
> words in the interface, the secret words you use to discuss them
> (since those are the words your tech support people are likely to
> learn by listening to you), and at least one synonym users are likely
> to think up on their own.
>
> The second is that most documentation provides no way to look up
> things you can see on the screen. I've occasionally had problems with
> Adobe documentation, for example, because they'll write something like
> "to fram statically, use the framistat tool" without showing me what
> that tool looks like or where it's hidden. Guys... if I knew how to
> fram statically, I wouldn't be reading the documentation. Provide a
> picture, please, or tell me which menu to look in!
>
> But that also leads to an index-related suggestion: provide a visual
> index too, particularly for things that don't have obvious names. The
> last manual I read that provided such assistance (15 years ago?) was
> the one for the AmiPro wordprocessor, which helpfully included a bunch
> of visual references so you could learn what things were called _and
> then_ use the word index to look them up. This may have been in the
> days before "tooltips" (aka hovertext), or during the early days when
> they weren't easy to create, but it does lead me to wonder how many
> people have not learned that tooltips exist. I'd bet serious money
> it's far more people than we think.
>
> The problem arises because we technical writers are word geeks and
> thus tend to forget that visual things are best looked up visually --
> particularly when there's no way to hold the cursor over something and
> wait for a popup to tell you what it is, as in the case of Word's
> border formats. Even a single "weird things you may see on the screen
> and what they mean" page would help.
>
> ------------------------------------------------------------------------
> Geoff Hart (www.geoff-hart.com)
> ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
> ------------------------------------------------------------------------
> Effective Onscreen Editing:
>http://www.geoff-hart.com/books/eoe/onscreen-book.htm
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
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! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
