Tackling Technical Writing(dev.to)
dev.to
Tackling Technical Writing
https://dev.to/alainakafkes/tackling-technical-writing
21 comments
>"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.
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.
Great quote! Thank you for sharing.
I wrote a detailed post[0] (also on dev.to) about how to write technical posts. Submitted it earlier today but didnt hit the front page. Hope you find it useful. Feel free to ask questions.
[0] https://dev.to/yelluw/how-to-do-technical-blogging
[0] https://dev.to/yelluw/how-to-do-technical-blogging
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.
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 received some feedback from a coworker about some of my writing to avoid the passive voice. I'm not sure where I developed my passive voice habit (maybe in my Chem 101 lab reports?) but it's been a hard one to break.
Is active voice always better?
Is active voice always better?
Active voice makes it easier to explicitly identify the doer in a tranasaction. Consider
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.
X will record the meeting decisions and supply them to Y
The meeting decisions will be recorded and supplied.
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.
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.
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.
> The thing performing the verb may not be relevant or may be actively distracting to mention.
That's exactly what I was thinking when I mentioned my Chem 101 lab reports.
I tend to write in a passive voice and if I read my words out loud rather than silently, it's obvious to me. It's almost sounds like I'm using cop talk (the subject was observed exiting the vehicle).
That's exactly what I was thinking when I mentioned my Chem 101 lab reports.
I tend to write in a passive voice and if I read my words out loud rather than silently, it's obvious to me. It's almost sounds like I'm using cop talk (the subject was observed exiting the vehicle).
> 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
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
The example I use to explain it to myself:
"The file may be deleted at a later date."
Would "The user may delete the file at a later date" fix the issue and still remain passive? What would be the best way to word this?
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."
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."
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...
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.
Point taken. Your edit is much better.
Thanks.
Thanks.
I guess it's worth mentioning that the original was also in the active voice. I agree the edit improved it; it's just not a change of voice.
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.
I don't like hard-and-fast rules, but I do prefer the active voice in most situations.
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.
"The most important thing to remember about technical writing is that the goal is not necessarily to be understood, but rather to avoid misunderstanding. As such, consistency and clarity are paramount, and you should never assume your reader has the knowledge you possess.
"I try to make sure to tell readers not only how to do something, but why. That way they are not just following instructions and learning by rote, but rather, they're building their understanding of the system you're explaining, and perhaps can devise solutions to problems you haven't covered."