RE: Which style of giving instructions is more effective?

Subject: RE: Which style of giving instructions is more effective?
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: Kat Kuvinka <katkuvinka -at- hotmail -dot- com>, Roberta Hennessey <rahennessey -at- gmail -dot- com>, Ryan Pollack <ryan -at- clicksecurity -dot- com>
Date: Wed, 19 Dec 2012 15:18:38 -0500

Ah. I swing both ways on this one.

I see the argument for trimming words.

I also see the problem when ending a sentence with a command.

What if the command MUST not have a terminating period - which is often the case for command-line stuff?

Now you'll get complaints that you left a sentence un-terminated. Tsk!

As well, I generally prefer to word my lead-in such that the command
can be shown alone on the next line:

command -parametername <value> [-option <value>] [-otheroption <value>] [-force]



> -----Original Message-----
> From: Kat Kuvinka
> Sent: December-19-12 2:37 PM
> To: Roberta Hennessey; Ryan Pollack
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: RE: Which style of giving instructions is more effective?
>
> To restart the device, enter <command itself>
>
> Trim some of the fat.
>
>
> >
> > IMHO, Restart is more active.
> >
> >
> >
> > On Wed, Dec 19, 2012 at 12:24 PM, Ryan Pollack
> <ryan -at- clicksecurity -dot- com>wrote:
> >
> > > 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

The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.


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


References:
Which style of giving instructions is more effective?: From: Ryan Pollack
Re: Which style of giving instructions is more effective?: From: Roberta Hennessey
RE: Which style of giving instructions is more effective?: From: Kat Kuvinka

Previous by Author: RE: When to use the word "curate?"
Next by Author: Re: When to use the word "curate?"
Previous by Thread: RE: Which style of giving instructions is more effective?
Next by Thread: Re: Which style of giving instructions is more effective?


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

Sponsored Ads


Sponsored Ads