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: Silly but important to me From:Suzanne -dot- Cole -at- pattersondental -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 1 Sep 2004 10:18:51 -0500
Whether to separate the results from the action may depend on the overall
document design.
What I mean is, does the document tend to combine different pieces of
information (such as more than one discrete action per procedure step/task,
or among process steps, include knowledge items, i.e., good-to-know but not
task-critical information)? In this case, the reader may expect to see the
result of an action immediately included with the action.
Or, does the design separate and sort discrete information types: are they
very distinct? If so, you'll need to separate these two different pieces of
information.
Is the document now or may it in the future be part of a content management
system, with XML and metadata and all? If so, does the result ever occur
from some other action, or solely the action you're recording? That may
direct the granularity and design for you.
Sometimes spacing is an issue. When the document is written on a custom
page size, or perhaps uses tables to control page layout, or the text is
dense, how much room do you have to work with?
Sometimes you might simply need choose a method, write the document, and
run a usability test to find out whether the readers themselves notice and
use the information, or whether they have other helpful comments.
In all cases, I'd avoid passive tense completely (as in, the dialog "is
displayed" or "is opened"). Clearly written instructions use direct, active
voice, so the result of each instruction should maintain consistency. I'd
write "the xxx dialog opens" or "this opens the xxx dialog."
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! 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- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
