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. For example:
    • Select the Tag checkbox to enable tagging.
    • Download Eclipse from the Salesforce Developers website.
  • Omit You can when possible as it unnecessarily increases word count.
  • Use the third person when the information isn't directed at a specific user, though this sometimes means using the passive voice. For example: If this header isn't used or the value of its element is null, the opportunities are transferred to the forecast manager in the specified territory.
  • Be aware of the various, possible contexts for the information. Some text is extremely sensitive to context, and procedures or explanations of how a feature or component works must be written with different user contexts in mind. This is because the person reading the documentation is most likely not the one issuing the command or method under discussion. Developers may read information that they need to know to write a client program that actually executes the command, so phrases like you or your organization aren't always right.
  • See also First Person.