Re: Syntax preferences

Subject: Re: Syntax preferences
From: Anthony Davey <ant -at- ant-davey -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 23 Aug 2005 22:16:31 +0100


Hi Mats,

Ignoring all the stuff that's gone on, about which way to turn the focus ring, I'd go for your first option. It follows the 'given-new' rule, which still makes sense for me when I read instructions.

First the given piece of information, that which the reader already knows (what they want to do), followed by the new information (how to achieve it).

In this example it's nice and easy, but I just hate sentences that tell me to select the ZZZ option from the YYY list in the XXX menu. I have to read the sentence, then re-read it backwards to find out where I need to start from. Although a slightly different situation, the argument is still 'which piece of information does the reader need first?'

Best regards,
Ant

Broberg, Mats wrote:

Dear all,

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.

An example:

- To adjust focus, turn the ring.

- Turn the ring to adjust focus

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.



References:
Syntax preferences: From: Broberg, Mats

Previous by Author: Books on CSS - recommendations please
Next by Author: Re: New TECHWR-L Poll Question - Why discuss certification?
Previous by Thread: RE: Syntax preferences
Next by Thread: Re: Syntax preferences


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


Sponsored Ads