RE: The 'user' in User Manual

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

Allow me to stave off an argument before it happens.  There was an argument
that I used grammatical terms incorrectly.  This is wrong.  I used terms
that may be used in grammar but they are used in the real world too.  So
when I say "grammatical terms are not necessary," I am not saying that I
will not use terms that do not have correlates in grammar, I am only saying
that I do not need to use grammatical terms to describe semantics.

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 Lauren
> Sent: Monday, February 05, 2007 11:13 AM
> To: 'Sarah Bouchier'; 'Techwr-l'
> Subject: RE: The 'user' in User Manual
> 
> 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 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.