TechWhirl Sponsors

About TechWhirl

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.

"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 :-)
-----------------------

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.