RE: Which style of giving instructions is more effective?

["Porrello, Leonard" <lporrello -at- illumina -dot- com>]

There is no best way. The form you use should depend on context and audience. Are you writing procedures or a reference?

If a procedure and the step is a necessary part of a process, you'd want to give the user the command up front: "Enter [COMMAND] to restart the device." If, on the other hand, the step is one that a user may not want to execute immediately (or at all), you'd want to say, "Restart the device by entering [COMMAND]" so that the user knows what he getting into before executes the command.

If a reference, you'd probably want to information map it with other commands. In that case, you could put the command in the first column or the result of the command in the first column--depending on what your audience would find most usable.

For what it's worth, I don't like starting procedural steps or references with prepositions (for example, "To" in "To restart ...."). Prepositions don't give the reader useful information.





-----Original Message-----
From: techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lporrello=illumina -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Ryan Pollack
Sent: Wednesday, December 19, 2012 9:24 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Which style of giving instructions is more effective?

Hi all,

I'm debating the merits of two different styles of commands:

"Enter the following command to restart the device:"

(followed by the command itself)

and

"Restart the device by entering the following command:"

(followed by the command itself)

I've been flipping back & forth on these for years; now that I am creating a new documentation set, I'd like to be consistent, if that is even possible (or desirable).

Any thoughts on the relative merits of each style? Situations when either would be useful? etc.

Thanks for your input!

-- 

Ryan Pollack
Senior Technical Writer | Click Security ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Writer Tip: Create 10 different outputs with Doc-To-Help -- including Mobile and EPUB.

Read all about them: http://bit.ly/doc-to-help-10-outputs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as lporrello -at- illumina -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Writer Tip: Create 10 different outputs with Doc-To-Help -- including Mobile and EPUB.

Read all about them: http://bit.ly/doc-to-help-10-outputs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives