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.
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.)
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.
In most cases, second person is best. It fits Atlassian’s casual, conversational tone to refer to the reader directly.
In general, use second person in your docs rather than first person—you instead of we.
Use second person (“you”) when speaking to or about the reader.
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.
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.
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.
- 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.
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.