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.
Mats Broberg wondered: <<In a one-sentence step in a procedure, do you
prefer to start the sentence with the result, or with the action to
achieve the result? I need to decide on a general policy in our
documentation.>>
It depends. <g> Where it's important to establish the context before
the user performs the action, the context must clearly come first: "To
avoid public humiliation, click the Edit button before sending your
message to techwr-l." If the context is crystal clear, there's no need
to provide that context either at the beginning or end of the sentence.
Consider your focusing example:
Focusing the camera
1. Hold the camera securely.
2. Turn the focus ring.
The heading establishes the context (focusing), so that context does
not need to be repeated. In the first step, the secondary context is
sufficiently clear that you don't need to make it explicit (i.e., you
don't want to drop an expensive device). If circumstances suggest that
the context is not clear, then you do need to make it explicit. For
example: "Because the focus ring is very stiff and may tear the camera
from your grasp when you turn it, hold the camera securely."
Obviously, it can become a very subjective judgment call as to whether
the context is necessary up-front. That being the case, the
conservative approach is to set a rule that context must always come
first for the sake of safety and consistency. This rule ensures that
the context is read before the action both when the context is crucial
("to avoid certain death, do the following") and when it's not ("to
close the dialog box, click OK").
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
---
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.
