Second person

In general, use second person in your docs rather than first person—"you" (sometimes implicit) instead of "we."

It's also important to figure out who the "you" is that you're addressing (the developer? an end-user? a sysadmin? someone else?), and to be consistent about that. Make it clear to the reader who you expect them to be (sometimes with an explicit "Audience" section near the beginning of the document).

Example of "we" vs "you":

Not recommended: If we're deleting multiple entries at a time ...

Recommended: If you're deleting multiple entries at a time ...

Also recommended: When deleting multiple entries at a time ...

(But if you're using an implicit "you" like the one in that last example, be sure that it's clear who's doing the deleting.)

In an instruction, leave out the "you." For example:

Not recommended: Let's click Submit now.

Not recommended: We now click Submit.

Slightly better: You now click Submit.

Recommended: Click Submit.

This issue can also interact with tense:

Not recommended: You'll need to create an XML entry.

Recommended: Create an XML entry.

If you have to use "we," it's better to use the active-voice "We recommend" than the passive-voice "It is recommended."

However, it's generally best to avoid "our". For example:

Not recommended: For details, read our documentation.

Better: For details, read the documentation.

Recommended: For details, read All About Pandas.

Send feedback about...

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide