Active voice

In general, use active voice (in which the grammatical subject of the sentence is the person or thing performing the action) instead of passive voice (in which the grammatical subject of the sentence is the person or thing being acted upon), though there are exceptions.

One reason for that: in passive voice, it's easy to neglect to indicate who or what is performing a particular action; in this kind of construction, it's often hard for readers to figure out who's supposed to do something. (The reader, the computer, the server, an end user, a visitor to a web page, ....)

Examples

Not recommended: The service is queried, and an acknowledgment is sent.

Recommended: Send a query to the service. The server sends an acknowledgment.

It's possible to indicate who's performing the action in passive voice (using "by"), but the resulting prose is generally not as good as if you were to recast the sentence as active voice. So whenever possible, make the doer the subject of the sentence.

Examples

Not recommended: The service is queried by you, and an acknowledgment is sent by the server.

Recommended: Send a query to the service. The server sends an acknowledgment.

Exceptions

In certain cases, it's okay to use passive voice. For example, passive can be okay in the following instances:

  • To emphasize an object over an action.
  • Recommended: The file is saved.

  • To de-emphasize a subject or actor.
  • Not recommended: You created over 50 conflicts in the file.

    Recommended: Over 50 conflicts were found in the file.

  • If your readers don’t need to know who’s responsible for the action.
  • Recommended: The database was purged in January.

다음에 대한 의견 보내기...

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide