
Tackling Technical Writing - uyoakaoma
https://dev.to/alainakafkes/tackling-technical-writing
======
mcone
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."

~~~
altotrees
>"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.

------
pryelluw
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
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._

------
criddell
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?

~~~
munificent
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.

~~~
criddell
> 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_ ).

