RE: Which style of giving instructions is more effective?

Subject: RE: Which style of giving instructions is more effective?
From: Fred Ridder <docudoc -at- hotmail -dot- com>
To: <hbailey -at- ocztechnology -dot- com>, <ryan -at- clicksecurity -dot- com>
Date: Thu, 20 Dec 2012 08:55:41 -0500


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

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


Follow-Ups:

References:
Which style of giving instructions is more effective?: From: Heidi Bailey

Previous by Author: RE: Back again.... looking...
Next by Author: RE: Back again.... looking...
Previous by Thread: 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