RE: Which style of giving instructions is more effective?

Subject: RE: Which style of giving instructions is more effective?
From: Heidi Bailey <hbailey -at- ocztechnology -dot- com>
To: Fred Ridder <docudoc -at- hotmail -dot- com>, "ryan -at- clicksecurity -dot- com" <ryan -at- clicksecurity -dot- com>
Date: Thu, 20 Dec 2012 06:15:07 -0800

"It's another application of the techwriter mantras: "it depends" and "know your audience". One size (one approach) does not fit all situations."

How true.

I do have to use such constructs in step-by-step instructions occasionally though, as some of what I write about is so complex, and each task quite long, that I have to give the user an idea of what a particular step achieves. (no they can't be broken down into smaller tasks; yes the overall task is explained separately at the start.)
And occasionally the user has to choose which action is relevant for them at that step, also making this construct a good choice (in a set of bullets).

So I wouldn't restrict usage to certain positions in the information - as you say, it depends what's needed :-). My intention was not to preach consistency for its own sake, but to point out how helpful consistency is in simplifying reading + understanding.

This is one of those subjects that many people can contribute to, modifying others' contributions and adding a vast number of tweaks to what is said.
For the sake of concision, I'll duck out of this one now :-)
-----------------------

From: Fred Ridder [mailto:docudoc -at- hotmail -dot- com]
Sent: 20 December 2012 13:56
To: Heidi Bailey; ryan -at- clicksecurity -dot- com
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Which style of giving instructions is more effective?

Heidi Bailey wrote:
> Many of us were taught that you tell them what they're gonna do, then tell them how.
> So in your example, "To restart the device, enter the following command:" is the correct form.
>
> Same with things like cross references: "To learn more about Blah, see chapter 6, Blah Blah on page n."
>
> This level of consistency is definitely good and desirable - the fewer sentence patterns a user has to churn through, the quicker they read and find what they need...

This approach is appropriate for a reference manual that users will turn to when they need to find out how to accomplish a particualr task or operation within a task.

But I would argue that it is much less appropriate for steps within a procedure, which I think may have been the context for the OP's query. In that context, the only "to do X" phrase belongs at in the introduction to the overall procedure along with something like "perform the following steps:". Once you're describing the sequential steps, the intermediate result produced by each step is (largely) extraneous detail since the overall objective requires *all* steps to be performed. I would argue that the individual instructions within a procedure should focus on the action to be performed and any confirming indication, and not be overly concerned about what the result of the specific operation is. I think a much more usable document results if the conceptual "this is what needs to be done" information is presented separately (e.g., in a summary or flowchart) from the procedural "this is how you do it" information that focuses on actions and indications.

It's another application of the techwriter mantras: "it depends" and "know your audience". One size (one approach) does not fit all situations. If you've done the work of analyzing your users' tasks and understanding how and when they will need to refer to your documents, that knowledge will suggest what approach is appropriate in what context. Consistency is a wonderful thing, but only when it serves the needs of your users. Don't impose a single approach in the name of consistency or "correctness" when two or three approaches (each used consistently within its own context) will result in more usable documentation.

-Fred Ridder

CONFIDENTIAL COMMUNICATION: This communication including any attached file(s) is CONFIDENTIAL, intended only for the named recipient (s) above and contains trade secrets or other information that is exempt from disclosure under applicable law. Any use, dissemination, distribution or copying of this communication and any file attachments by anyone other than the named recipient (s) is strictly prohibited. If you have received this communication in error, please immediately notify us by reply electronic mail and permanently delete the original transmission and any attachments from your computer system and any copies of this message and file attachments. Thank you.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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: Heidi Bailey
RE: Which style of giving instructions is more effective?: From: Fred Ridder

Previous by Author: Which style of giving instructions is more effective?
Next by Author: TECHWR-L Premium Jobs, Events, and Announcements
Previous by Thread: RE: Which style of giving instructions is more effective?
Next by Thread: Re: User friendly is what you get used to


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


Sponsored Ads