Tackling Technical Writing

Great quote! Thank you for sharing.

>"The most important thing to remember about technical writing is that the goal is not necessarily to be understood, but rather to avoid misunderstanding.

That quote is fantastic. Having worked as a Technical Writer, the problem I most often run into is what I term the "forest for the trees" issue. Oftentimes, I work or did work with engineers who knew a language, framework or low-level system inside and out. Sometimes they even spent their entire adult lives learning it. When it came time to communicate the essentials of said technology or language, it was almost like they froze, unable to go back to basics or build concepts from the ground up. If it wasn't high-level or advanced, they stumbled.

I was often brought into situations like these with little knowledge of what I might be asked to write about. I was usually given the option of starting a project by interviewing engineers, but often delayed that and did a bit of my own research first. Once I had the most basic of concepts and understanding locked down, I would guide the engineer toward those areas, and have them start remembering their earliest introduction to whatever their area of expertise was. I found that was oftentimes the best way to avoid being misunderstood — not for me to understand everything 100 percent, but to get those who did to break things down into the simplest terms and build things up.

Nice! One thing I struggle with is removing I/me/mine from writing. When you do, it almost always condenses the thought and makes it simpler to understand. E.g., in your post you could combine the first two sections and halve your word count:

Intro

Many software developers blog to share technical knowledge and experiences. Some don't realize that sharing that technical knowledge is a skill they must develop on top of basic blogging skills.

This post explains how to structure a technical post, provides examples, and includes personal tips.

Looks like it's on the front page now :) Great write up.

I don't like hard-and-fast rules, but I do prefer the active voice in most situations.

Active voice usually requires fewer words to express the same idea. As a result, the language becomes more direct and clear.

So my opinion is that, yes, active voice is almost always better.

But holy cow is it a hard habit to break...

Active voice presents less conceptual noise. OP could have written, "A coworker advised me to avoid the passive voice," which not only uses fewer words (which is not inherently a virtue, in my opinion), but also requires less conceptual modeling to understand.

The example I use to explain it to myself:

    "The file may be deleted at a later date."

The passive disguises the actor. Who is going to do the deletion? You, when you eventually start tidying up, or the system, when it runs out of room?

Active voice makes it easier to explicitly identify the doer in a tranasaction. Consider

   X will record the meeting decisions and supply them to Y

vs.

   The meeting decisions will be recorded and supplied.

In any sort of situation where responsibilities must be explicitly identified (e.g. a contract), active voice can really help. You can make responsibilities clear in passive voice as well, but active voice is more direct and less stilted. In situations where the doer is unimportant, passive is okay ('experiment data was logged'), but I still think sounds clunky.

Coming back to the wider point about not being misunderstood, two rules that I apply are the 'make responsbilities explicit' one I've just discussed, and "make sure it is obvious what 'it' and 'this' refer to". As a writer of technical content, you should never make the reader have to work to figure out what you mean.

Steven Pinker goes into this in The Sense Of Style. It's not always better, but you're right that a lot of bad writing overuses the passive voice to seem 'professional', etc.

I've found in my own writing that when I start to use the passive voice I often either don't fully understand what I'm writing about, or am embarrassed by what I'm documenting. Passive voice seems to be an easy way to hand-wave.

> Is active voice always better?

I recommend this talk by Dr. George Gopen, which does include some advice on the use of the passive voice: "A Radical New Way to Control the English Language" https://www.youtube.com/embed/XuGII3MzBic

> The writing instruction we received in school was inadequate to prepare us for writing in the adult, professional world. We were taught how to avoid grammatical errors and how to write a 5-sentence paragraphs and 5-paragraph essays. None of that is of use when we try to write grant applications or technical manuals. The writing advice we get (if any) as adults is equally inadequate: We are told to avoid the passive, to keep our sentences short, and to write the way we speak – all very, very bad advice. In school, the important person where writing was concerned was the writer. In the real world, the important person becomes the reader. Concerning the quality of a piece of professional writing, one simple question dominates: Did the reader get delivery of what the writer was trying to send?

The part about the passive voice is at 15m10s but I encourage you to watch the whole talk from the beginning. It is worth it.

If you want more, some of his writings are easy to find online: https://duckduckgo.com/?q=george+gopen

In my experience, the passive voice weakens a statement because a verb's subject is vague or undefined. As a result, the reader must go through additional cognitive steps to parse the statement.

Especially in technical writing, using an imperative verb is generally more efficient and effective.

E.g.: "The process is completed by clicking OK."

Reader: "Who completes the process? I do. How? By clicking OK."

vs: "To complete the process, click OK."

Reader: "To complete the process, I click OK."

Always, no, Usually, yes. And, since most people overuse passive voice, advice to avoid using it benefits most writers.

Passive voice hides the thing that is performing the verb in the sentence. That obscurity has some costs. It tends to make the sentence longer. See "benefits most writers" above instead of "is beneficial to most writers".

Worse, it tends to make the sentence harder to "get into". You want the reader to concretely visualize what you're saying. When the sentence gives you no actor to place in the scene, it's harder to grasp what's really going on. That vagueness in turn makes your writing harder to understand and harder to remember.

On the other hand, sometimes you really do want to hide the actor. The thing performing the verb may not be relevant or may be actively distracting to mention. It may be that one or more actors may be the thing that performs the verb and you don't know which one it will be. Being specific could be incorrect. In those cases, I think passive voice is fine.

But as a first approximation, "avoid passive voice" is good advice. Be skeptical of every use it, and don't be equally skeptical when you use active voice. But don't tie prose in knots trying to avoid passive voice entirely. Sometimes an "is" is fine.