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.
Subject:Re: we recommend From:Janice Gelb <janiceg -at- MARVIN -dot- ENG -dot- SUN -dot- COM> Date:Thu, 18 Jun 1998 08:47:53 -0700
mattbin -at- hotmail -dot- com wrote:
>
> I, too, write manuals in the second person, and I agree that "we
> recommend" is a bit of a wrench in terms of style.
>
> I also agree with those who have said that starting a sentence with "it
> is" is weak. It is. Er, I mean, I think this is true.
>
> If there is only one best way, the recommendation should be implied. I
> mean, most applications have three ways to perform most functions (menu,
> toolbar, keystroke, for example), so one is limited to providing the
> best solution, and possibly informing the user that other solutions
> exist in some way, such as an introductory section.
>
> However, when a number of different solutions, each with pros and cons,
> we owe it to the user, I think, to explain the differences between the
> solutions, the potential outcome of each, and then make a qualified
> recommendation, in a conditional clause.
>
Our style calls for writers not to use either "we recommend"
(we don't allow first person plural anywhere in our docs) or
"it is recommended" (because of the indefinite it); we just
go ahead and tell the user what the best thing is to do.
In cases where there are several ways to do something and they
each have advantages, I agree with presenting each way and
its advantage. In cases where there are several ways to do
something but one is clearly quicker (such as pressing Alt-B
rather than choosing Insert Block Elements from the Markup
menu), I think that in the very beginning of a tutorial or
explanatory material you present the longer method, also
provide the shortcut there, and provide the shortcut only
from then on.
********************************************************************************
Janice Gelb | The only connection Sun has with this
janice -dot- gelb -at- eng -dot- sun -dot- com | message is the return address. http://www.geocities.com/Area51/8018/index.html
"Editor: Someone whose job requires the knowledge that `carpe diem'
is not the fish of the day."
