RE: The second person in user guides

Subject: RE: The second person in user guides
From: "David Farbey" <dfarbey -at- yahoo -dot- co -dot- uk>
To: <beth -dot- agnew -at- senecac -dot- on -dot- ca>, "'List,Techwriter'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 4 Dec 2005 14:42:32 -0000

The fashion for informal language in user guides was a reaction to a formal
and impersonal style which wrote about "The user". For many non technical
audiences the formal style was ineffective. It did not help the people
reading the manual to do their jobs more easily.

As Beth wrote, the key to the correct style and tone is understanding the
audience for a particular publication. Engineers (in every discipline)
sometimes need reminding that they themselves are not usually typical
representatives of the people who are going to read the manuals we write.

David Farbey,
London UK

-----Original Message-----
From: techwr-l-bounces+dfarbey=yahoo -dot- co -dot- uk -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+dfarbey=yahoo -dot- co -dot- uk -at- lists -dot- techwr-l -dot- com] On Behalf
Of Beth Agnew
Sent: 03 December 2005 00:09
To: List,Techwriter
Subject: Re: The second person in user guides

It always comes back to audience. What is the best style for your customers?
While the "you" is implied in the imperative, you may have occasion to
address the reader directly. For example: Click the New Record button. Enter
customer data into the fields provided. In the Notes field, you may want to
add information that helps you remember details about the previous meetings
you have had with this customer.

The style you choose will depend on the publication, the audience, and the
tone you are trying to set with that particular user group. A guide is just
that, a set of good practices that it is recommended one follow for
consistency. If there exceptions, as long as they are applied consistently,
your publications will work.
--Beth

Sagendorph, Wallace wrote:

>Some have suggested that to engage the readers, we should write the
>companion guide in a breezy, casual style using the second person ("you
>should do this," you should not do that," "your document should
>include," blah, blah). Others say this is tantamount to an approval of
>such usage in formal documents, and is unnecessary in any event --- the
>imperative mood ("do this," "don't do that") works as well or better,
>and it does not imply that "you" and "your" should find their way into
>documents released to publications or the public.
>
>
--

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Re: The second person in user guides: From: Beth Agnew

Previous by Author: Re: Programming Languages: A *Useful* Comparison?
Next by Author: RE: Merry Christmas vs. Bah, humbug!
Previous by Thread: Re: The second person in user guides
Next by Thread: Re: The second person in user guides


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


Sponsored Ads