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.
Ruby Isaacs reports a colleague's question: <<"I am working on a manual of
procedures concerning safety for inspectors and have come across a mishmash
of text that switches from....declarative statements such as 'Inspectors
must always....' to ones addressed directly to the reader that are
imperative such as 'you must never ... you are required to be....' My
instinct is to improve the text by choosing to describe inspectors' actions,
but at the same time I am concerned that the message may be more
successfully delivered by the imperatives.>>
It sounds like the manual is mixing contextual information, such as
regulatory requirements, with task-based information, such as what the
reader must do within that context. Thus, you might see something like "The
law says inspectors must wear a shirt and tie. Thus, wear a shirt and tie."
While both kinds of information are useful, mixing them too freely can lead
to schizophrenic documentation in which the reader is never sure whether the
next sentence presents them with a fact or tells them what to do.
The most effective solution is to extract conceptual information into an
introduction or other overview that primes the reader to take on the task;
that text can be declarative while still being effective. ("Here's the
situation...") Then, present the task as a series of imperative statements.
("Do this, then that, then a third thing.") Imperative voice works best for
instructions because it's concise and doesn't leave any doubt as to who the
actor is. Compare:
- declarative: "Inspectors must be aware of the need to button their
shirts."
- imperative: "Button your shirt."
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out RoboDemo for tutorials! It makes creating full-motion software
demonstrations and other onscreen support materials easy and intuitive.
Need RoboHelp? Save $100 on RoboHelp Office in May with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
Free copy of ARTS PDF Tools when you register for the PDF
Conference by May 15. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
