Second person and first 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.

It's generally best to avoid "our."

Not recommended: For details, read our documentation.

Better: For details, read the documentation.

Recommended: For details, read All About Pandas.

フィードバックを送信...

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide