grammar - User tutorial: to be written in first or second person?



I'm writing a user tutorial but I'm unsure as to what perspective it should be written from e.g., first, second? The tutorial is a friendly guide showing how the user should do x.


Example:



Viewing your file there are some special instructions you should be familiar with.


Viewing our file there are some special instructions we should be familiar with.


..and refers to the version we want to install.


...and refers to the version you want to install.



Which is correct?



Answer



Having written several user manuals, I can offer the following from experience:




  1. Consistency is very important. It's really easy to accidentally slip into: "The user should click this button. You should see this result." So once the decision is made, stick with it. (As an aside, this is an especially troublesome issue when the user manual is large and written by multiple stakeholders.)




  2. There are three options: first person (usually plural), second person (usually singular), and third person (either singular or plural). There is no "wrong" choice, but there are expectations and opinions that you might want to take into account.




  3. First person places the emphasis on the software creator, rather than the reader. This is usually a bad idea (my opinion), because the reader is interested in how the software will benefit/impact him, not how the software has been shaped by the author. Even using the "royal we" does little to assuage this.




  4. Second person is acceptable, especially for somewhat less formal usage, but the repetition of "you" over and over becomes tiresome. Usually this ends up being simple imperatives ("Click this button"), which are fine for many cases, including a sequence of directions.




  5. Third person is the most formal and (my opinion) the most widely accepted for narrative, particularly formal official documentation. It does, however, get a bit awkward for lengthy step-by-step directions. Singular vs. plural doesn't seem to make much difference, but if the author uses both singular and plural forms in the same section, there should be a good reason for doing so (versus mere accidental inconsistency).




Given the above, my preference is to use third person singular for block text and narrative, and second person singular (imperative) for directions. For example:



The key system functions are available to the user after logging in. In order to perform x, the user must first perform task y. The user can accomplish the task from either the menu bar or the navigation bar, as follows:




  1. Click button n.




  2. Read through the terms and conditions.




  3. Acknowledge the terms and conditions by clicking OK.




  4. Select an option from the navigation menu on the left.





Comments

Post a Comment

Popular posts from this blog

verbs - "Baby is creeping" vs. "baby is crawling" in AmE

Years and years ago, I remember reading in a book on AmE usage that the phrasal turn a baby creeps before it walks was to some extent more common to AmE than to BrE, which preferred exclusively the "crawl" version. And so, I just recently checked on the accuracy of that information on NGram Viewer , and it actually was fact... more than a century ago! What I would like you to tell is if it would sound sort of weird to hear someone say today in the US that a child "creeps" before walking and running (see Synonyms ) rather than it crawls. Also, what's the story to those terms? How did "to crawl" come to prevail and supersede "to creep" to describe the way a baby moves around? As with a plant, so with a child. His mind grows by natural stages. A child creeps before he walks , sits before he stands, cries before he laughs, babbles before he talks, draws a circle before he draws a square, lies before he tells the truth, and is selfish before he
Read more

commas - Does this sentence have too many subjunctives?

Does this sentence have too many subjunctives? If it please the king, let it be decreed that they be destroyed, and I will pay 10,000 talents of silver into the hands of those who have charge of the king's business, that they may put it into the king's treasuries. I am stumped by this sentence construction. First, there is "Let it be," which is a common English idiomatic phrase, but then it follows another subjunctive. Is that to say you can actually have a subjunctive followed by another subjunctive? Also, why does the sentence use "please"? If that's the subjunctive tense there, then why is it followed by another subjunctive instead of a conditional, or maybe "Let it be" is the conditional? Lastly, I wish to know how the that is used in the sentence. Perhaps, the simplified sentence can be restated like so: Let it be decreed that they be destroyed and that they may put it into the king's treasuries. If not, maybe the simplified sent
Read more

time - English notation for hour, minutes and seconds

I often see English notation about time using the " and ' symbols. I have always mistaken about the two, and even their meaning. I'm more used to "01:05:56", for example. How do you represent the hour, minutes, and seconds using the apostrophe and quotes punctuations? Which is for the hour, which is for minutes, and which is for seconds? Is it the common way to write duration of time elapsed? Do they have a special pronunciation? Answer It's not particularly common for expressions of time. It's similar to degrees-minutes-seconds: instead of decimal degrees (38.897212°,-77.036519°) you write (38° 53′ 49.9632″, -77° 2′ 11.4678″). Both are derived from a sexagesimal counting system such as that devised in Ancient Babylon: the single prime represents the first sexagesimal division and the second the next, and so on. 17th-century astronomers used a third division of 1/60th of a second. The advantage of using minute and second symbols for time is that it o
Read more

grammatical number - Use of lone apostrophe for plural?

I've been reading William Manchester's book "American Caesar", which is about Douglas MacArthur, and I found that he uses a strange convention for pluralizing the family name. When talking about the MacArthurs as a whole, he writes MacArthur' with an apostrophe, as in "After the war, the MacArthur' lived in Tokyo while the general was proconsul" (yes, he uses that term to describe him). I have never seen or heard of a rule that would prescribe this. Manchester is a bit old-timey in his style: for example, he also writes "in behalf of" instead of "on behalf of", which is the only one I have ever seen. So perhaps this is similar. Where does he get this apostrophe from? Edit: There seems to be some difficulty finding examples, which is odd. Here is a direct link to a page from Google Books that shows the apostrophe.
Read more

etymology - Origin of "s--t eating grin"

What is the origin of the phrase shit eating grin ? How did it come to mean showing smugness or self-satisfaction of an individual's actions? Answer From the Urban Dictionary: ...these uses are documented in the Oxford English Dictionary no earlier than 1957 There have been similar expressions used quite far back: In Book XXI of his History of Rome, Livy describes a Carthaginian sect of coprophages, the risus faecivorus, or shit-eating grin, being commonly displayed by its adherents. Although, its origin is undetermined, they may have been incidents which caused the invention of this phrase. Below is an excerpt: "1944 Jrnl. Nerv. & Mental Dis. XCIX. 959 Among demented patients in advanced stages of their illness,..it is not rare to see some of them grasp their own feces, chew them and eat them often with great pleasure and satisfaction (coprophagia).
Read more

etymology - Where does the phrase "doctored" originate?

This is a phrase I’m particularly confused about, because it’s used often when something is manipulated or changed. For example, sometimes images surface online that are clearly Photoshopped, but people refer to them as “doctored” images. Why use the word “doctored” here? Answer The earliest Google Books match for an instance of doctored in a transitional (or perhaps post-transitional) sense between "amended" and "adulterated" appears in William Marshall, The Rural Economy of Glocestershire; Including Its Dairy: Together with the Dairy Management of North Wiltshire, and the Management of Orchards and Fruit Liquor, in Herefordshire , volume 2 (1789): Men in general, however, whose palates are set to rough cider, consider the common sweet sort as an effeminate beverage; and rough cider, properly manufactured, is probably the most generous liquor; being deemed more wholesome, to habits in general, than sweet cider:—even when genuine. That which is drank, in the kingd
Read more

word choice - Which is the correct spelling: “fairy” or “faerie”?

Fairy vs. faerie — which is the correct spelling? Answer As others have noted, fairy is the standard modern spelling, and faerie is a pseudo-archaism. However, in some contexts there is now a semantic distinction between the two spellings! In particular, fairy tales and the associated idea of fairies typically refer to the genre of folk stories printed by the Brothers Grimm, then sweetened and popularized for modern audiences by Disney et al. Faerie stories , on the other hand, are stories about the fae : otherworldly, unpredictable, and dangerous creatures who appear in the folk-tales and myths of England and Ireland. In origin, of course, the fairies and the fae are one and the same, but the connotations and usage of the words today are headed in opposite directions. A Google image search for fairy vs. faerie shows a lot of overlap, but some very significant differences in tone and content between the two terms. Note that the search for "fairy" turns up a number
Read more