4 ms·

Tackling Technical Writing

74 points by uyoakaoma 9y ago

mcone 9y ago
One of my favorite tech writing tips came from an email exchange with Owen Linzmayer, the author of Apple Confidential (No Starch Press): "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."
- jotjotzzz 9y ago
  Great quote! Thank you for sharing.
- altotrees 9y ago
  >"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.
criddell 9y ago
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?
- noelwelsh 9y ago
  I don't like hard-and-fast rules, but I do prefer the active voice in most situations.
- zzalpha 9y ago
  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...
- gglitch 9y ago
  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.
  - criddell 9y ago
    Point taken. Your edit is much better. Thanks.
    - abecedarius 9y ago
      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.
- cormullion 9y ago
  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?
pryelluw 9y ago
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 https://dev.to/yelluw/how-to-do-technical-blogging
- rcjones 9y ago
  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.
- pandyzhao 9y ago
  Looks like it's on the front page now :) Great write up.

74 points by uyoakaoma 9y ago

One of my favorite tech writing tips came from an email exchange with Owen Linzmayer, the author of Apple Confidential (No Starch Press): "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."

jotjotzzz 9y ago
Great quote! Thank you for sharing.
altotrees 9y ago
>"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.

criddell 9y ago

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?

noelwelsh 9y ago
I don't like hard-and-fast rules, but I do prefer the active voice in most situations.
zzalpha 9y ago
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...
gglitch 9y ago
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.
- criddell 9y ago
  Point taken. Your edit is much better. Thanks.
  - abecedarius 9y ago
    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.
cormullion 9y ago
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?

pryelluw 9y ago

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 https://dev.to/yelluw/how-to-do-technical-blogging

rcjones 9y ago
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.
pandyzhao 9y ago
Looks like it's on the front page now :) Great write up.