Re: Capitalizing...research need
SW is not our main business (our SW "product" is a tool that our
customers use to configure and install our main product), so to be
frank we don't expend as much effort on our SW docs as we do
on the rest of our products, but one convention we do follow is to
not pepper the instructions with the names of dialogs or windows
over and over again. The bolded title is used once at the beginning
of the instruction, and thereafter the text refers only to its contents,
says "this tab," or something along those lines. We also make heavy
use of screen caps, numbered callouts and fragmented statements
(example: if there's a button called "Run," there's a numbered arrow
pointing at it in the screen cap, and below the figure a description
that says "(#) does blahblahblah," rather than "Run button: does blahblahblah").
I have never liked illustrations that use numbered arrows and then a separate key to desribe what each number points to. Why create that extra cognitive load when you could design an illustration (in many cases) where the callouts themselves do the explanation?
Using phrases such as "this tab" can be OK if you're sure that users know what you're referring to, that they will not go away and be in, say, onther tab when they get to that part of the content.
And I have to ask: Do you think customers notice not as much effort on the software docs (and is there less effort on the that software too), and if so, doyou think they might actually ask themselves that if there's not much effort put into those part, how can they be confident that effort *was* put into the "main" product?
"Chuck Martin" <cm -at- writeforyou -dot- com> wrote in message news:...
The bolding catches users' eyes (like links on a web page), and too much bolding distracts them from important points. More often than not, the most important points are going to be your procedural text; users are reading the docs because thay can't figure out from the interface how to get a particular task done. If the interaction points are the only ones bolded, users can just scan the bolded text and get a very good idea of what to do without even reading comprehensively.
--
--
Chuck Martin
User Assistance & Experience Engineer
twriter "at" sonic "dot" net www.writeforyou.com
"I see in your eyes the same fear that would take the heart of me.
The day may come when the courage of Men fail, when we forsake our
friends and break all bonds of fellowship. But it is not this day!
This day, we fight!"
- Aragorn
"All you have to decide is what to do with the time that is given you."
- Gandalf
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
Technical Communication Certificate online - Malaspina-University College, Canada. Online training in technical writing, software (FrameMaker, RoboHelp, Dreamweaver, Acrobat), document & web design, writing manuals, job search. www.pr.mala.bc.ca/tech_comm.htm for details.
---
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.
Previous by Author:
RE: techwr-l digest: February 10, 2005
Next by Author:
Re: Capitalizing...research need
Previous by Thread:
RE: Lost Password in Acrobat 6
Next by Thread:
RE: Capitalizing...research need
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads