TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
