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: For references or directives, do you say where/why and then what/how, or vice versa?
Subject:Re: For references or directives, do you say where/why and then what/how, or vice versa? From:Andrea Shanahan <amshanahan -at- gmail -dot- com> To:Lin Sims <ljsims -dot- ml -at- gmail -dot- com> Date:Thu, 16 Aug 2018 20:52:21 -0400
100% with you on this! It's something recently discussed on my team. I keep
looking for evidence supporting this view.
Fwiw, I found this in the online MS style guide, which appears to support
what I call "context first" :
By "context" I mean orientation, whether it's location on a menu or in a
field, for example, while tending to avoid giving "traffic directions" like
"far left top corner") or the purpose or intent of the actionâi.e., that
which is to be accomplished.
Unless a step is either very short and/or obvious ("Click Save"), or unless
it's redundant or pedantic to do so, "context first" almost always works.
On Aug 16, 2018 2:26 PM, "Lin Sims" <ljsims -dot- ml -at- gmail -dot- com> wrote:
I was reminded of this question during the earlier thread on whether to use
"see" or "reference" and decided a nice philosophical argument would be a
good way to round out the week. :)
My preference has always been to tell people why or where they're doing
something and then telling them what to do. This was a result from an
online training I took years ago that gave instructions such as:
"Type Foo in the Baz field."
on a really crowded screen, so you had no chance to FIND the Baz field
before the training had moved on through 5 more fields.
That experience is why I decided I'd be writing my instructions in the
following format, even if I had a screenshot with callouts:
"In the Baz field at the top right of the screen, type Foo."
Similarly, if I was referring people to someplace else for more
information, I'd word it as:
"For information on fiddling the thingbub on the Baz, see What's a Baz and
Why Do I Care?"
But I recently came out of 5 years in a job where the style was to give the
action first, as in:
"Type Foo in the Baz field."
or
"See What's a Baz and Why Do I Care? for information on fiddling the
thingbub on the Baz."
I've never liked that. I can understand that convention was used because
they wanted everything to be a direct instruction and to have the
instruction right up front, and normally I'd agree with them; but these are
two situations where I feel it's more important to tell the where or the
why before telling the how or the what.
Who has strong preferences for one versus the other, and why?
--
Lin Sims
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | http://techwhirl.com
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
