Syntax preferences?

Subject: Syntax preferences?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 23 Aug 2005 09:28:40 -0400

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").

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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!

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 for more resources and info.

Syntax preferences: From: Broberg, Mats

Previous by Author: Indexing a 212-page tech document using WORD '03? (take II)
Next by Author: Correct Usage of Terms?
Previous by Thread: Re: Syntax preferences
Next by Thread: RE: Syntax preferences

What this post helpful? Share it with friends and colleagues:

Sponsored Ads