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:Janice Manwiller <jmanwiller05 -at- yahoo -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 17 Aug 2018 11:16:03 +0000 (UTC)
I also strongly believe in putting what the user is doing or looking for first, so they can verify that that's what they really want to do before taking an action.
I just think it's clearer and helps avoid unintended actions.
"Click OK ..... (user clicks OK) .... to completely erase your hard drive and launch the missiles."
An extreme and sort of silly example, but I still like having that chance to confirm.
Janice
------------------------------
Original message
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
