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

Shauna writes:

>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.

-- Robert
Robert Plamondon
President, High-Tech Technical Writing
robert -at- plamondon -dot- com
(541) 453-5841

Previous by Author: Re: extra words: unnecessary or educational?
Next by Author: Dreamweaver and RoboHelp
Previous by Thread: FrameMaker Tools and Plug-ins
Next by Thread: digest mode

What this post helpful? Share it with friends and colleagues:

Sponsored Ads