RE: The 'user' in User Manual

["Lauren" <lt34 -at- csus -dot- edu>]

I was focused on the function of the document and the approach required to
develop a document that functions as it should.  When an author sees himself
as a communicator to the audience, then he writes himself into the document.
This is an excellent approach for marketing where a document will shout to
the audience "You need this product!"  This is the wrong approach for a
technical document because it gives the reader a sense that he *must* do
something.  So the best technical documentation does not include the author
or the reader.

A way to understand this is to think, "Is the document directly telling
someone something as a person-to-person communication?" or "Is the document
a how-to of a process that should reflect how the reader should think to
complete the process?"  In the first sense, pronouns are necessary, in the
second second sense, pronouns are distracting and detract from the document.
This is not a grammar issue but an issue of semantics.  Grammar governs the
form of written language and semantics governs the function of language.

I was never and am not now concerned with grammar.  People who keep posting
about grammar (after following the thread) have totally missed the
discussion of semantics in favor of a side argument about grammar.  The
discussion of semantics is broader than the discussion of grammar.  Grammar
is for writing only.  Semantics covers all language that includes writing
and thought.  What I discussed was a thought process.  Another summary of
the concept that I was conveying is "Think like the mind of the reader."
People do not think to themselves "You must do this."  They think "Do this."
This concept is semantical and not grammatical, so grammatical terms are not
necessary and in the case of people like me who do not know the terms, they
are confusing.

> > That means no "I," "You," "He," "She," "the User," etc.
> >should be in the document.
> 
> It's a theory I've tried to follow, but I've been unable to 
> manage it in all situations.  I'd appreciate any tips from 
> those who fare better than I :)

I learned several years ago that pronouns were inappropriate in technical
communication and have made the habit of not using them.  I spent more time
developing this skill while I learned it than I do now.  I challenge myself
by re-writing bad communication just to prove to myself that no writing must
have a person in it to function.  Marketing documentation, correspondence,
and other types of communication, of course, benefit from pronouns, but they
can be written without them. Technical communication should not have
pronouns, except of course when a third-party to the communication is
referenced, as in a system administration document that mentions the user.
A user manual should never refere to "the user." Provide an impossible
example and I will re-write it.

> What do you mean by 'without specifying a direction'?  The 
> way I think of it, in a document saying 'click the pretty 
> shiny button' there is plainly a direction; the 
> document/author is telling me to do things.  I don't think I 
> can be understanding what you mean; can you clarify?

Direction means that the communication is directed to someone.  As I have
tried to make clear in this message, technical communication should read as
though it is coming from the reader's own mind and is not directed to the
reader as it is when "you" is stated.

Lauren

> -----Original Message-----
> From: techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com 
> [mailto:techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com] On 
> Behalf Of Sarah Bouchier
> Sent: Monday, February 05, 2007 10:28 AM
> To: Techwr-l
> Subject: RE: The 'user' in User Manual
> 
> >Please cite the message where, as you say, I said "Don't use 
> 2nd person 
> >voice."  I said to not use "you" and that is in 2nd person 
> voice.  The 
> >original discussion is about the use of the word "you" if you will 
> >remember.
> 
> I believe that the only point Richard is trying to make here 
> is that while the word 'You' is not present in the second 
> person imperative, the second person imperative is still, 
> fundamentally, in the second person.
> You may be taling at cross-purposes.
> 
> In the course of this discussion we have ended up talking 
> about grammar; it's therefore useful to use the grammatical 
> terms people know.  There is nothing +wrong+ with using 
> alternative, but this discussion has just proved what all 
> technical authors already know; using nonstandard terms is a 
> fruitful source of confusion.
> 
> >I continued to say that it is best to take a neutral stance in 
> >documentation.  Neutral means that neither the author or the audience
> is in
> >the document.
> 
> Nobody has suggested that 'neutral stance' is undersirable.  
> All that has been said is that the 'neutral stance' of which 
> you speak is better known as the imperative; specifically, 
> the second person imperative.
> The 'you' is not spoken, but it is implied; the 'neutral' 
> phrase 'Use no pronouns!' does not mean 'He must use no 
> pronouns' or 'I must use no pronouns'; it means that the 
> person being spoken to must use no pronouns.
> 
> This is worth knowing, since some readers may experience 
> slight cognitive dissonance if they are directly addressed 
> using the imperative during parts of the manual, but then 
> spoken about in the third person ('...the user will notice 
> slight confusion...') during other parts.
> 
> Of course, if you can keep from mentioning the user entirely 
> that's another thing entirely, but I've come across a few 
> occasions when I can't actually do that without rewording the 
> part in question to be a lot less clear.
> 
> > That means no "I," "You," "He," "She," "the User," etc.
> >should be in the document.
> 
> It's a theory I've tried to follow, but I've been unable to 
> manage it in all situations.  I'd appreciate any tips from 
> those who fare better than I :)
> 
> > Without specifying a direction toward author or audience, 
> the document 
> >is neutral.
> 
> What do you mean by 'without specifying a direction'?  The 
> way I think of it, in a document saying 'click the pretty 
> shiny button' there is plainly a direction; the 
> document/author is telling me to do things.  I don't think I 
> can be understanding what you mean; can you clarify?
> 
> > I really never expected neutrality to be seen as a new concept.
> 
> Avoiding the use of pronouns and pronoun-substitutes in a 
> document is a pretty old concept.  But that is all your 
> 'neutral stance' (the
> imperative) is; it is simply a form of the second person in 
> which the persons are implied rather than actively spoken.
> 
> S.
> (Who hopes she is understanding correctly)
> 
> Sarah Bouchier
> Technical Author
> exony
> 
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> Create HTML or Microsoft Word content and convert to Help 
> file formats or printed documentation. Features include 
> single source authoring, team authoring, Web-based 
> technology, and PDF output. http://www.DocToHelp.com/TechwrlList
> 
> Now shipping: Help & Manual 4 with RoboHelp(r) import! 
> New editor, full Unicode support. Create help files, 
> web-based help and PDF in up to 106 languages with Help & 
> Manual: http://www.helpandmanual.com
> 
> ---
> You are currently subscribed to TECHWR-L as lt34 -at- csus -dot- edu -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/lt34%40csus.edu
> 
> 
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
> 
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwr-l.com/techwhirl/ for more resources and info.

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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com

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


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

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