There is No You in API: A Case for Passive Voice in API Documentation
By Robert Delwood, a Lead API Documentation Writer
Some API style guides exclude the use of second-person pronouns such as you. And for good reason. In API documentation, there may be statements such as:
· “Use this request when you have your customer’s processId.”
· “…you want to find out the amount…”
· “…you pass the processId as an input…”
At best, the use of you is too informal. At worst, it’s wrong. The use of you is misleading in these cases because in API documentation it’s unclear who is making the action. This is one difference between API documentation writers and technical writers. For technical writers, they are writing directly to the user. You is appropriate then. In API documentation, it is not always clear who the user of a request is. We get used to the fact the audience for API documentation is the client developer, and we write to them. Almost feeling a companionship with them.
The truth is, it’s not clear who the audience for a specific request is. The client developer is a developer who is using the documentation to write an application. It is unlikely that the client developer is going to also be the audience for their own application. They’re writing it for someone else. The audience could be an end user to the client developer. The audience may not even be a person. It may be a system call that uses that request automatically, or as part of a larger process. Therefore, saying you becomes inappropriate, because it addresses the wrong audience.
The best workaround is not to use you. However, that gets into passive voice. We are schooled from an early age that active voice is always preferred. “Bill threw the ball” reads clearly and precisely. But only because we care about the actor, or the person performing the act. If the focus were on the ball, then “The ball was thrown by Bill,” becomes acceptable. If the focus was exclusively on the ball, then adding an actor actually complicates the point. Is the point that the ball was thrown, or was thrown by Bill? If “The ball was thrown,” conveys the exact intent of the writer, then it’s the right sentence. The actor isn’t important and, so, should not be mentioned.
This is the case for API documentation. As mentioned earlier, we neither always know who the actor is, nor do we always care. So why mention the actor? The important point is the request requires a valid processId, for example. Grammatically, this is valid, too. The following are legitimate cases for passive voice:
· The actor is unknown
· The actor is irrelevant
· You want to be vague about who is responsible
· You want to emphasize the thing acted on
· You are writing in a scientific genre that traditionally relies on passive voice
For these reasons, being technical writers doesn’t make us members of a literary society. We can’t use elegant variation, for example. Elegant variation is the writing mechanism that allows authors to use different words, synonyms, or even indirect references, to refer to the same item. That intent is to make reading more exciting or interesting, and, so, not to bore readers with the same term all the time. Any Bulwer Lytton fan knows the heroine leans salaciously against the love seat, settee, chesterfield, davenport, daybed, divan, futon, ottoman, chaise longue, convertible couch, sofa bed, and window seat. You’d think she’s in a furniture warehouse. No, it’s the same one piece of furniture.
And that’s precisely what technical writers have to guard against. We’re not here to be exciting or interesting. We have to always use the same term to refer to the same item. Our job is to clarify concepts and to be explicit during procedures. Using different terms in technical writing is imprecise and confusing. Furthermore, pity the surgeon who has to locate the artery and then bypass that “pulsating, life-giving red highway of hemoglobin goodness.” Pity us writers as well: Precision comes at a cost.
Use active voice where it makes sense. But understand that passive voice isn’t a grammatical error; it’s a matter of style. It’s your friend when the thing receiving an action is the important part of the sentence — especially in scientific and legal contexts — when the performer of an action is unknown or in cases where the performer distracts or is irrelevant.