Musings on Business and Tech

This Piece of Technical Writing Has Been Written By Me

In my role as a business analyst at a software development shop I see a lot of technical writing, much of it terrible. For some reason, people whose job it is to be precise and logical often fail to do so when the language of expression is English, rather than Java. While the problems in technical writing are varied, the offense I most often see is overuse of the passive voice.

For those who don’t remember their junior high school grammar, passive voice is a grammatical construct in which the object of a sentence is repositioned as its subject. “Tom throws the ball” is active voice, while “The ball is thrown by Tom” is passive. The use of passive voice in itself is not grammatically incorrect, but it often weakens the clarity of the writing by obscuring who or what is doing the action in the sentence.

Technical writing is a veritable breeding ground for passive voice proliferation, in many cases because the actors in technical writing are not tangible. The actors are software code, or systems, or networks. My phone today popped up an alert that said, “The server cannot be reached.” Who exactly is the one not reaching the server? Is it the phone? Is it the app I was running? Is it me?

But just as a writer would avoid passive voice in “normal” English prose, so too should a technical writer avoid it in his work. Phrasing technical ideas in the passive voice dampens the agency of the thing doing the action, making it seem unfamiliar and disembodied. Technology does things. To render technology in the passive voice is to distort its power to create change.

This is especially evident when technical writing refers to error conditions, as in the case of the alert above. It’s almost as if the authors of the software were deflecting blame away from themselves with the message, “The server cannot be reached.” They could just as easily have said, “It’s not our fault that you can’t access this page. Talk to the dudes who run the server.” (People in IT love to blame the other guy, but that’s a story for a different post.)

It’s never that difficult to clean up language like this in one’s technical writing, but it often requires ascribing some degree of agency to to the technology. Instead of “The server cannot be reached,” one could write it as, “The application failed to reach the server,” or, “The application failed to connect to the server.” If English had a better indefinite subject pronoun, we could even write something like, “One cannot reach the server at this time.”

There are any number of solutions to the problem of passive voice in technical writing. The main thing is to be aware of the easy pitfall, and to think about technology more as an agent of change than as some hidden force behind the things we observe.