Daniel D. Beck

The second person is OK in developer documentation (but don’t take my word for it)

If you’ve written any technical documentation, you’ve probably dealt with, implicitly or explicitly, the question of grammatical person: should you address the reader directly with “you”, “your”, and “yours”?

Perhaps you or a well-intentioned colleague feels that the second person is not OK. It’s not just that every writer knows the “helpful” colleague with idiosyncratic style tips. Most of us have years of practice in the formal style preferred in schools and universities, which forbids the use of “you” and “I”.

Nevertheless, “you” has a real appeal. Addressing the reader directly feels more conversational. The second person makes it easier to avoid dull, passive sentences. For those reasons, you might be drawn to the second person, but find it’s difficult to convince yourself or your colleagues that the second person is an acceptable style.

Instead of trying to make the case on your own, I invite you to appeal to authority. Many writers and editors have dealt with this question before you. And they’ve got one unmistakable answer.

Many, many style guides agree that the second person is useful for documentation, including developer documentation.

It’s possible this is one of the only guidelines for which contemporary style guides have true consensus. Every style I guide I could find—from Microsoft, Google, Apple, and more—says to use the second person. Take a look for yourself. Below, I’ve quoted and linked to the verdict from every technical style guide I know of.

(And if this list is helpful, then don’t miss my next post. Subscribe to my newsletter below.)

Apple

The Apple Style Guide on the word user:

If the audience of your document consists of users, avoid this term. Instead, address the reader as you.

When the audience consists of developers or administrators, use user to refer to end users and you to address the developer or administrator.

Atlassian

The Atlassian Design System on Pronouns:

In most cases, second person is best. It fits Atlassian’s casual, conversational tone to refer to the reader directly.

Google

The Google developer documentation style guide on Second person and first person:

In general, use second person in your docs rather than first person—you instead of we.

IBM

The IBM developerWorks editorial style guide on A modern editorial style:

Use second person (“you”) when speaking to or about the reader.

Microsoft

The Microsoft Style Guide says, “In general, use second person”:

In second person, you write as though you’re speaking to the reader. Second person often uses the personal pronoun you, but sometimes the word you is implied. It supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the reader.

Rackspace

The Rackspace Style Guide on Write to the user by using second person and imperative mood:

Users are more engaged with content when it talks to them directly. You talk to users directly by using second person, addressing the user as you. Second person also promotes a friendly tone.

Red Hat

The Red Hat Style Guide on Gender references:

In most cases, use “you” when giving instructions, and “the user,” “new users,” and so on in more general explanations. Do not use “one” in place of “you” when writing technical documentation. Using “one” is far too formal.

Salesforce

The Salesforce Style Guide for Documentation and User Interface Text on Second Person, Third Person:

  • For user documentation and UI text, use the second person, you, which makes the writing more informal and personal.
  • In user documentation, use the imperative voice whenever possible.
  • In UI text and both user and developer documentation, you or the imperative is almost always appropriate in procedures, since the person reading the documentation is usually the same person trying to perform the task.

Splunk

The Splunk Style Guide on Pronouns:

Most of the topics in Splunk documentation use the second-person singular pronoun, “you” and “your”, to address a single user directly.


Know of any more? Let me know about them and I’ll add them to this list.