Re: Which style of giving instructions is more effective?

[Ryan Pollack <ryan -at- clicksecurity -dot- com>]

Well-said, Leonard. I like your advice. Thank you!

-Ryan


On Wed, Dec 19, 2012 at 2:49 PM, Porrello, Leonard
<lporrello -at- illumina -dot- com>wrote:

> 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
>



-- 

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 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