Use of the second and third person in documentation?

Subject: Use of the second and third person in documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 24 Feb 2005 11:20:26 -0500


Anthony Hernandez wondered: << Is it standard practice to refer to users of software a "the user" or "users," or as "you"? Examples: 1. Users can click... 2. You can click...>>

There's no such thing as a standard, but there is a strong trend towards something like the following distinction:

- Where you're trying to establish an informal dialog with the reader, as might be the case in an overview section or the introduction to a tutorial, it's acceptable and possibly even a good idea to use second person. For example: "In this section, you'll learn how to..." and "Before beginning this long procedure, you should get a cup of coffee and good book."

- In the procedural steps themselves, use imperative and don't mention the user at all unless absolutely necessary. For example: "Click this. Press that. Open something else. If you have a life, go home and get some sleep. If you're a manager, make sure that _your employees_ have lives outside of work--send them home."

I find this distinction simple and effective. YMMV. Be consistent, whichever approach you choose.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at www.componentone.com/techwrlfeb.

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- 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:
Use of the second and third person in documentation: From: A.H.

Previous by Author: Wanted: "Right" Standards for User Manual (appliance)?
Next by Author: Button vs. Icon?
Previous by Thread: RE: Use of the second and third person in documentation
Next by Thread: Re: Use of the second and third person in documentation


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


Sponsored Ads