1

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?

closed as off-topic by user140086, Edwin Ashworth, Kristina Lopez, tchrist, Jim Dec 22 '15 at 23:39

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Proofreading questions are off-topic unless a specific source of concern in the text is clearly identified." – Community, Kristina Lopez, tchrist
If this question can be reworded to fit the rules in the help center, please edit the question.

  • @Rathony - The OP has just added second quote; it was not there when I viewed the question and submitted the edit for peer review. – Dinesh Kumar Garg Dec 22 '15 at 16:56
  • 2
    Why not look at some existing user tutorials that you think are particularly good, and imitate them? – GEdgar Dec 22 '15 at 17:01
  • @GEdgar I have and it differs from tutorial to tutorial. Some even use first, second and third interchangeably (don't pick me up on interchangeably :). – Spike Dec 22 '15 at 17:06
  • Maybe the question "which is correct" is wrong. Maybe I should be asking, "which is better" or preferred for this type of writing? – Spike Dec 22 '15 at 17:09
  • @Spike Welcome to EL&U. This site is not well-equipped for asking about "better" or "preferred" as it often comes down to a matter of opinion. Writers.SE might have more to say, and this is really a question about writing rather than language. – choster Dec 22 '15 at 17:14
3

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.

  • Wow, I was not excepting such a detailed answer! This makes a lot of sense. Second person fits my style of writing and your point on consistency is well taken. Thank you. – Spike Dec 22 '15 at 17:15

Not the answer you're looking for? Browse other questions tagged or ask your own question.