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.
Youbiquitous (was Re: extra words: unnecessary or educational?)
Subject:Youbiquitous (was Re: extra words: unnecessary or educational?) From:"Robert Plamondon" <robert -at- plamondon -dot- com> To:<techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 29 Aug 2003 07:09:20 -0700
>In User documentation, the focus may be on procedural information, and the
>"How" from the user's perspective, but Design documentation focuses on the
>functional and technical information, and the "How" from the developer's
>perspective. The two examples he gives are dramatically different when
>viewed in these two contexts; the first is more appropriate for User docs,
>whereas the second is more appropriate for Design docs.
>Meaning does not exist independently from context. Audiences may vary.
True enough. Mind you, even in end-user documentation, it's no fair hiding
the tools and features from the user, only revealing glimpses of them when
you absolutely have to, in the midst of procedures. I hate that.
At some point, every manual should cough up an inventory of all the tools
and features, describing their knobs and switches and what happens when you
twiddle them. The whole concept of not giving the users a map, but simply
leading them down a few selected garden paths, only works for very simple
Generally speaking, I think writing this portion of the manual in the second
person is fatuous. It doesn't all have to be about "you." The inappropriate
use of the word "you" can be annoying, condescending, or vaguely
disturbing -- and not just when the sentence runs afoul of the vast number
of euphemisms in English, such as, "Tighten your nuts with the 5/16''
wrench." There are times when you should just tell the reader how the damned
thing works and leave him out of it.