
Undervalued Engineering Skills: Writing Well - gregdoesit
https://blog.pragmaticengineer.com/on-writing-well/
======
lpolovets
Writing well is an undervalued skill in life, not just in engineering. When
you work on a team of peers with similar skills in your field, whether that
field is engineering or something else, being able to write well and
communicate well become strong differentiators. FWIW, I'm pretty sure that
writing (reasonably) well online is what got me a job in venture capital after
ten years as an engineer.

David Perell (host of the North Star Podcast) has been tweeting a lot of good
things about the value of writing + writing tips:

\-
[https://twitter.com/david_perell/status/1127348174404890625](https://twitter.com/david_perell/status/1127348174404890625)

\-
[https://twitter.com/david_perell/status/1124002449646395392](https://twitter.com/david_perell/status/1124002449646395392)

\-
[https://twitter.com/david_perell/status/1116485842615377921](https://twitter.com/david_perell/status/1116485842615377921)

~~~
afarrell
In what sense is it _under_ -valued? There is a fabulously popular musical
about how the ability to write well can propel you to the heights of
leadership of a nation. In my experience, people believe that the ability to
write well is key to professional success.

Where are the people who believe that writing is not a valuable skill?

~~~
JamesBarney
In the sense I've never seen any interview require a writing sample from a
dev.

~~~
thrower123
You have to write at least a few coherent, error-free paragraphs in your
resume typically. It's something of a good filter to toss out people that
either can't, or can't be bothered to, write clearly for that small sample.

~~~
sonnyblarney
People generally don't read prose in technical resumes, moreover, I'd never
hold it against a candidate because they're nudged into writing in a highly
summarized, notation style. Unless there were blatant issues with language,
and then I'd be super concerned about blowing off an 'english as a second
language candidate'. About 1/2 of devs it seems are from 'somewhere else' and
we can't expect them to have world class technical chops and perfect fluency.

------
jsty
I agree with the author that writing is one of the most undervalued skills for
SWEs, but for a completely different reason - it forces you to reason things
through properly, even if nobody else will ever read what you write.

Writing a couple of pages of design docs or an Amazon-style 6 pager or
whatever might take a few days of work, but can save weeks or more of wasted
implementation time when you realise your system design was flawed or it
doesn't address any real user needs.

~~~
bloopernova
I'm currently trying to get some folks on the same page regarding the most
basic of things in a design document, and the passive resistance is just
astonishing to me.

Just adding the following text seems to upset some people:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119.

It's like they don't want to be pinned down to an exact meaning in design
documents! And don't even think about trying to "force" people to use a style
guide like RFC 7322, or even an authoritative list of initialisms, acronyms,
and abbreviations.

Is it too much to ask to have people use the same term to refer to a project,
environment, component, etc? It saves so much time when you don't have to
spend effort tracking down what someone means when they say "stage is broken".

This has already gotten too rant-y but it burns my butt so much! So much
wasted effort!

~~~
chrisseaton
I don’t think the key to effective writing is following a bunch of standards.

~~~
technofiend
>I don’t think the key to effective writing is following a bunch of standards.

Well it is if you're being judged on compliance to the standard. Have you
never worked in government? But hey if you don't like the standard then just
make your own: the great thing about standards is there are so many to choose
from!

~~~
briandear
It depends on what you are writing. Also, there is a question of readability.
A document written in legalese is certainly “accurate,” but that doesn’t make
it comprehensible. Writing with clarity isn’t about following a standard, it’s
about using language in such a way that the consumer of that language
understands the message. If documents were written following like the RFC,
they’d be incredibly tedious to read. English isn’t a computer language, there
is a such thing as context, tone, and diction. Of course if you are actually
writing a legal document or standards document, certainly use that idiom.

------
Maro
This resonates with me. My writing is clear and concise, I'm proud of it, and
it pays off because I can communicate effectively.

I'm not sure I agree with the "undervalued", in so far that I see a _lot_ of
people who are not able to write clearly, and they get ahead and along just
fine. Many executives who I worked with wrote terrible emails (sometimes they
leave out the negation, so I'm guessing whether they mean X or not-X), and
they're super successful, in so far as their companies are successful / they
are in high positions.

Sometimes the Amazon protocol comes up (before a meeting, the organizer
submits the topic in writing, everybody has to read it before), and I always
cringe - in my experience most people just can't write a clear 2 page document
[or can't be bothered]. I would love it tough.

~~~
alexpotato
I wonder if they have a junior person that does/did the writing for them.

Reminds me of a story about fighter pilots from World War 2. Some of the best
fighter pilot aces had, at best, average vision. Their coping strategy for
this was to find pilots who weren't as good at dogfighting but had excellent
vision as wingmen.

Both parties benefited since the better pilot could spot enemy planes earlier
and the lesser pilot got to fly with an ace and occasionally get kills they
wouldn't have gotten otherwise.

~~~
aphextim
I recently got to ride in the co-pilot seat of our company plane and it was a
neat experience to see everything and listen to the radio chatter and the view
was amazing to watch the sun rise and the moon set at the same time.

He showed me how as a fighter pilot he was trained to spot other aircraft.

When one would show up on the radar he would point and be like see that plane
over there? I could never see it until we were very close and I have great
vision and no glasses.

After a few times of this game he then said, "Now when you are looking for
another aircraft you don't focus on where it is, scan your eyes left to right
horizontally".

Now I was able to pick out the what seemed like 1-2 pixel dot in the distance
by not trying to focus on the dot but look at everything else and your brain
somehow figures out the anomalous pixel/dark spot against the horizon.

It reminded me a lot of when I was a kid bird hunting how my dad would try to
point at the partridge and it was the same game. You try to focus directly at
them and it was hard to see them in the brush, but scanning your eyes back and
forth helps make them pop out and be visible.

~~~
lightsighter
Actually there is some vision science behind this phenomenon. Your fovea is
what you use to focus on things and it's got lots of cone cells that are good
at picking up colors and specific details but are not so good at picking up
motion. The rest of your eye though has tons of rod cells that effectively see
just black and white, but are really good at doing motion detection (mainly to
recognize predators and prey in your peripheral vision). So instead of trying
to use your fovea to find the plane (which it really sucks at doing), you
instead keep your eye moving which exposes much more of the scene to rod cells
and let their natural motion detection abilities go to work.

~~~
sixstringtheory
There was a great article on this a while back:

“A Fighter Pilot’s Guide to surviving on the roads”
[https://www.portsmouthctc.org.uk/a-fighter-pilots-guide-
to-s...](https://www.portsmouthctc.org.uk/a-fighter-pilots-guide-to-surviving-
on-the-roads/)

> Only a small part of the retina, in the centre and called the fovea, can
> generate a high-resolution image. This is why we need to look directly at
> something, by moving our eyes, to see detail. The rest of the retina
> contributes to our visual experience by adding the peripheral detail — hence
> peripheral vision. Peripheral vision cannot resolve detail, which prevents
> the brain from being overloaded with too much information, but it is very
> good at detecting movement.

> Well, first, it is an unfortunate fact that if you are converging on a given
> point with another vehicle at the same speed, and assuming that you are both
> traveling in a straight line, then there is no apparent movement noticeable
> by the occupant of either vehicle. That is, to the driver of each vehicle,
> the other will remain in exactly the same position in the windscreen up to
> the point of impact. There is no relative movement — so our peripheral
> vision is not suited to detecting it.

> Now for the really interesting part. When we move our head and eyes to scan
> a scene, our eyes are incapable of moving smoothly across that scene and
> seeing everything. This makes perfect sense: just like trying to take a
> picture without holding the camera still. The image would be blurred. So,
> our clever brain overcomes this by moving our eyes (really fast, remember)
> in a series of jumps (called saccades) with very short pauses (called
> fixations and it is only during the pauses that an image is processed. Our
> brains fill in the gaps with a combination of peripheral vision and an
> assumption that what is in the gaps must be the same as what you see during
> the pauses.

Previously discussed:

\-
[https://news.ycombinator.com/item?id=12422378](https://news.ycombinator.com/item?id=12422378)

\-
[https://news.ycombinator.com/item?id=17900759](https://news.ycombinator.com/item?id=17900759)

------
simonw
The more experience I get as an engineer, the more time I spend writing
documentation, proposals, tutorials and the like.

This article is absolutely spot on when it points out that these skills become
increasingly important as the size of an engineering organization grows.

The biggest challenges in engineering at scale (scale in terms of complexity
and size of the team) are around communication. Good writing is how you scale
your communication, especially if your team aren't physically co-located.

I don't think software engineers talk about or think about how to improve
technical writing nearly enough.

~~~
bongobongo
The problem is that many organizations prevent their IT/engineering
departments from professionalizing in a way that would allow for this. "We
need a month to iterate over requirements and specification" can land like a
lead balloon in any project management meeting, because the _non_-engineers
don't see any value in it.

~~~
aphextim
When you try to explain to them that implementing a new system they want isn't
as simple as installing new kitchen cabinets.

Try to explain that it is like when you install a kitchen cabinet and then
open up the door and it leads to an entire new kitchen cabinet set which also
needs to be worked on and that cabinet also has it's own kitchen cabinets that
need redone as well.

A lot of times (at least where I work) management has a hard time seeing all
the layers in the IT systems they use and what appears to them as a simple
surface fix/change isn't always the case.

------
JoeAltmaier
My tech-write wife says the Engineer-writer fault she most often encounters is
the 'mystery story'. That's hiding the lead down at the bottom of an argument.
Because Engineers like to show their work and don't want to 'give away the
ending' until they've proved it right.

So put the conclusion right at the top somewhere! Sometime its as simple as
putting the last sentence of every paragraph at the beginning of the
paragraph.

~~~
ianmcgowan
It's about emails, but I like this article[0] about how topics are covered in
the military (where I imagine clear communication is important). "Military
professionals lead their emails with a short, staccato statement known as the
BLUF (Bottom Line Up Front). It declares the purpose of the email and action
required.". I find this helpful..

[0] [https://hbr.org/2016/11/how-to-write-email-with-military-
pre...](https://hbr.org/2016/11/how-to-write-email-with-military-precision)

~~~
EForEndeavour
The BLUF is exactly analogous to what the internet hivemind calls the tl;dr
(too long; didn't read). I almost always see the tl;dr as the last line of a
long post, when really, it makes a lot more sense to lead with it.

~~~
TeMPOraL
Seconded. I always put TL;DR at the beginning if it's meant as an actual
summary. I sometimes put a TL;DR at the end, when it's meant as a humorous
summary.

~~~
Wowfunhappy
It stands for "too long; _didn 't_ read." The operative word here is "didn't".

"If you started out trying to read this, but then realized it was too long and
just skipped to the end, here is what you missed."

------
apo
I noticed the article appears to contain a single point of evidence supporting
its main claim:

> Don't take this advice just from me. Take it from others, like employee #8
> and now SVP of engineering at Google, Urs Hölzle who also says that writing
> clearly is an important superpower for engineers.

The link goes to a LinkedIn page with a brief quote captured in raster image
format. This is weak evidence for a topic that will certainly be met with
strong resistance from the target audience.

The author could make a much stronger case by interviewing a few people at top
companies specifically on the topic of engineer writing. These people should
be in a position of making promotion decisions. The author might coax out of
them illustrative anecdotes that show exactly how poor writing skills can keep
an aspiring engineer down.

How much money in lost wages is my crappy writing costing me? What are my job
prospects if my writing doesn't improve? What exactly will better writing
allow me to do that I can't already do? These are all questions that demand
answers (and evidence) from people with 10 other things they might be doing.

Another idea: what studies (if any) have been done on the correlation between
writing quality and promotion within technical organizations? For that matter,
how does one objectively measure writing quality? After all, you're much more
likely to improve something you can measure.

A hallmark of good writing (of any kind) is ample evidence to support claims.
Engineers and scientists are a skeptical bunch, and so this point applies even
more to technical writing.

------
aresant
In a past life I helped optimize >$1b of online transactions as a CRO
professional and learning to objectively "write well" could be quantified in
two ways:

1) _Message Density_ \- there's a great quote attributed to Mark Twain that
nails this "If I'd had more time I would have written you a shorter letter".

In practice Jeff Bezo's push to making executives build "4 page memos" for
meetings outlines this idea clearly: "the reason writing a good 4 page memo is
harder than "writing" a 20 page powerpoint is because the narrative structure
of a good memo forces better thought and better understanding of what's more
important than what, and how things are related"(1)

2) _Message Accessibility_ \- Making your message broadly accessible is a good
forcing function to writing clearly. An easy "hack" in this department is to
utilize the "gunning fog index"(2) which is a structured way to estimate "the
years of formal education a person needs to understand the text on the first
reading" and there are many tools online that can spit out a score.

(1) [https://slab.com/blog/jeff-bezos-writing-management-
strategy...](https://slab.com/blog/jeff-bezos-writing-management-strategy/)

(2)
[https://en.wikipedia.org/wiki/Gunning_fog_index](https://en.wikipedia.org/wiki/Gunning_fog_index)

~~~
turingbike
Surprisingly, there are a lot of good tips in the US Gov's Plain Language
Guidelines
[https://www.plainlanguage.gov/guidelines/](https://www.plainlanguage.gov/guidelines/)

~~~
charliepark
That's an excellent resource. Thanks for sharing it.

------
mabbo
Amazon is obsessive about this stuff. I'm surprised the article never mentions
it.

There are internal classes offered on writing better documents (and it's a
great class). There's videos, guides, documents, everything. Writing well at
Amazon is key to a successful career here. Got a project idea? Write a very
good 1-pager explaining it and you've got a much higher chance of it actually
happening. Want to share a design? Write a 6-pager (often 10-15 pages with
appendices) explaining what, why and how you're going to build the system.

I've been in meetings that start with 15 minutes of silent reading, then 45
minutes of discussion. No PowerPoint presenting.

It's very weird for newcomers, but I don't know anyone who finds that it isn't
better than the alternatives.

~~~
funkymike
> I've been in meetings that start with 15 minutes of silent reading, then 45
> minutes of discussion. No PowerPoint presenting.

I wish this could happen where I am. No one wants to bother reading anything
ahead of the meeting to be prepared for a discussion. Then the same people
don't have the patience to let the group review the material during the
meeting before starting the discussion.

~~~
duxup
I WANT TO read ahead, but nobody tells me even what meetings are about despite
having company wide meetings on effective meeting and the first point was
about setting agendas and seating meeting goals and topics.

~~~
wool_gather
I've found just declining these no-info meetings to be an effective way to
combat the time loss. It's most constructive to send an email alongside saying
something like "please share an agenda or materials for this", but that can
vary based on context too. And you can even decline after that happens:
"Thanks for the details. I'm sorry, but I cannot take the time away from X
right now to attend this. Next week may be possible."

If somebody really needs my time, they can tell me why -- or go through my
manager which they should be doing anyways.

~~~
deathanatos
You say that, and it sounds like it ought to work, and yet…

I had to do that to a co-worker, and all I got back was "Product Foo". Okay,
but _what about_ Product Foo? Blood from a stone, every damn time, and it
wears _me_ down.

~~~
wool_gather
Well, that kind of reply is just rude, and personally I'd probably ignore it
and leave the meeting declined. If it comes up later, "Your reply about the
meeting? No, I don't think...oh, I did see it, right. I assumed there was more
info coming; I'm totally focussed on $X right now, you know."

------
kashyapc
Especially for those who work remotely, I (English is my third language) can't
overstate the importance of deliberately working on writing skills. As
remotees, we are often judged by our words, whether we like it or not. A
couple of recommendations:

• Many here might've already come across it, but is always worth bringing up:
William Zinsser's, _On Writing Well_. In which, he urges us to write with
"clarity, simplicity, brevity and humanity"; tells us "the intangibles that
produce good writing—confidence, enjoyment, intention, integrity"; reminds us
to "remember that what you write is often the only change you'll get to
present yourself to someone whose business or money or good will you need";
and much more.

• The equally excellent book, _Clear and Simple as the Truth_ [2]. In this
rigorous work, Thomas and Turner describe a style of writing that rests "on
the assumptions that it is possible to think disinterestedly, to know the
results of disinterested thought, and to present them without fundamental
distortion. In this view, thought precedes writing". And the book also has a
chapter that is aptly titled, _The Museum_ , a "guided tour through examples
of writing, both exquisite and execrable".

The second book, I suggest to slow-read it over a period of several months to
digest it (and perhaps even do the exercises in the chapter titled _The
Studio_ , if you're a non-native speaker), not least because, as a certain
Roman Stoic urged us, _to read attentively—not to be satisfied with "just
getting the gist of it"_.

[1]
[https://www.goodreads.com/author/show/7881675.William_Zinsse...](https://www.goodreads.com/author/show/7881675.William_Zinsser)

[2]
[https://press.princeton.edu/titles/9445.html](https://press.princeton.edu/titles/9445.html)

~~~
Bekwnn
I'd also recommend "It Was the Best of Sentences, It Was the Worst of
Sentences" for some easily digestible writing on how to write easily
digestible writing. It's probably one of the most useful type of writing skill
to have as an engineer.

------
beat
I used to be a huge proponent of learning to write well as the most important
skill an engineer can learn.

Now, I think it's the second most important skill.

The most important skill is _sales_.

The key value of writing well, in a workplace environment (or other
environments, really) is to convince others to agree with what you're
proposing. Convincing people that something they don't initially understand or
trust is going to be a win for _them_ is a sales problem. Clear writing is
only a means to that end.

~~~
beat
And as a follow-on comment rather than an edit...

There's nothing smarmy or dishonest about sales. Misleading sales is bad
sales. The best salespeople are focused on fulfilling the customer's needs,
not selling the product. The product sells itself once the customer
understands that it fulfills their needs and offers them real benefits
relative to the expense. And expense isn't just money. It's time. It's risk.
It's learning curves.

Customers often don't understand their own needs very well, so a big part of
sales is helping the customer understand their own problems, in order to
provide valuable solutions.

The engineer who can really dig into requirements, really get to understand
the customer and help the customer understand their own needs, and _then_
offers a working solution, with clearly stated benefits and clearly stated
costs, will do far better.

~~~
hyeomans
Do you have any good resources on sales?

~~~
beat
Start with _How to Win Friends and Influence People_ , by Dale Carnegie.
Ignore the cheesy-sounding title; this book was written in the 1930s and has
been in print continuously ever since, which speaks to its effectiveness. I
also recommend _To Sell Is Human_ , by Daniel Pink (and all of Daniel Pink's
other books, as well).

~~~
hyeomans
Thank you. I try to re-read How to win friends every year, there's always a
nugget of information that I remember.

I bought To Sell is Human, thank you for that one.

------
mnorton
I have kept around and distributed multiple copies of The Elements of Style,
by Strunk and White, for the past few years (lots of revisions of this out
there, 4th might be most recent iirc). It's like a 9$ book and the guidance is
priceless.

[https://www.amazon.com/Elements-Style-Fourth-William-
Strunk/...](https://www.amazon.com/Elements-Style-Fourth-William-
Strunk/dp/020530902X/ref=sr_1_3?crid=2MK6DSC2Y7SVJ&keywords=elements+of+styles+strunk+and+white&qid=1559316830&s=books&sprefix=elements+of+style%2Cstripbooks%2C144&sr=1-3)

~~~
lukeHeuer
Most of the guidance is very outdated. It's likely to confuse more than
clarify unless you've taken the time to study modern resources. I prefer Bryan
Garner's work, like his usage guides.

There is a great episode of Lexicon Valley where the dustier advice from The
Elements of Style is called out:
[https://podcasts.apple.com/ca/podcast/against-strunk-
white/i...](https://podcasts.apple.com/ca/podcast/against-strunk-
white/id500673866?i=1000394239451)

~~~
mnorton
There's definitely stuff in there that is dusty for sure. Thanks for this.

~~~
lukeHeuer
For sure. There are some great, valid points in it as well.

------
wazoox
Writing well can have several meanings. I've found that hilarious bug tickets
are much better received and treated than dry ones. Maybe because they get
many eyeballs (of the sort that makes all bug shallow).

Here is one of the first ticket I wrote in my still current company:

Then God appeared to wazoox and told him: "You will not spread your software
on the face of the world without properly testing the new features, so as not
to get into trouble with a rarely used tool that proves buggy with an
important customer. I said, and so be it." So it was done this way, and the
courageous people of the developers wrote unit test scripts, to validate the
proper functioning of each new version, whereas until now they were content to
test by hand and whatever popped into their heads. Then rivers of milk and
honey flowed on the earth, and the customers gave them much money; then the
Lord saw it and was pleased.

~~~
TomVDB
Please no.

Instead of a clear script, the developer now has first has to wade through
word diarrhea to extract meaning.

> Then God appeared to wazoox and told him: "You will not spread your software
> on the face of the world without properly testing the new features, so as
> not to get into trouble with a rarely used tool that proves buggy with an
> important customer. I said, and so be it."

This could have been replaced with: "First test new features before sending to
customer." ... ... I think.

What a way to waste time of your audience.

~~~
CalChris
You do have a point but still let's look at it another way.

It's a ticket. That means that at best it's boring and mundane. The writer
knows this and is trying to convince you, to sell you, on spending some time
thinking about it. Granted, you should do that anyways but _First test new
features before sending to customer_ doesn't really convince you to do that.
If your text was enough then maybe it should have been a check box and saved
everyone some time.

All that said, there is a time and place for humor. Maybe this was it and
maybe it wasn't. Dunno. Audience matters; timing matters; context matters.

------
tombert
I do find it a bit bizarre that the otherwise smart people that I work with,
with English as their first language, will often resort to writing emails and
documentation like a 14-year-old on AIM. I'm obviously much more forgiving of
people that had to learn English as adults, but somewhat paradoxically I find
that they typically write a lot more comprehensibly than most of the native-
speaking engineers.

I'm hardly John Steinbeck or Mark Twain, but I've always felt that if I wanted
to be treated like a grown-up, I should write like a grown-up, and as a result
I have tried to write well. I try and be understanding of typos, because those
are just honest mistakes, but when an adult sends an email to me saying
something like "when r u going to do this?", I get a bit annoyed.

~~~
enriquto
I used to think like that (being the kid that wrote well in school). But now
I'm not so sure anymore...

Been humbled too many times by people much, much smarter than me that wrote in
smsesque. Have read too many apparently well-written texts that are nothing
but bullshit written by ignorants.

~~~
tombert
Oh, most of my coworkers are smarter than me, so I'm certainly not trying to
make an assessment on their IQ or any nonsense like that.

That said, I _do_ think that writing smsesque (which I am going to steal for
the future because I had never heard that term before) is a really good way to
make yourself _look_ dumber, especially to non-engineers. Even if my long and
rambling writings lack substance, they still typically give the optics of
someone who is smart. Is that the way it should be? Probably not, but I don't
make the rules.

~~~
enriquto
> I do think that writing smsesque (...) is a really good way to make yourself
> look dumber, especially to non-engineers.

Maybe they do that in purpose, then?. They do not need to be admired by
everybody, especially not by non-engineers. Like the very rich people who
dress extremely humbly, with torn-down clothes.

~~~
Crinus
No they do not. I've seen a LOT of smsesque text that come from all sorts of
different people who i'm 100% they are not trying to "appear dumber". I do not
know why people do it, so i assume laziness. Smart people can be lazy too.

~~~
pests
In the end all writing or speech is about communicating an idea.

My opinion is these people have learned it doesn't matter. If an idea can be
conveyed in smsesque and still get the point across while being quicker to
write, then why not?

I have a feeling power/authority/expert status matters here because the
listeners will power through unclear communication just to gleam a glimpse of
the underlying idea from this idol.

~~~
blondin
exactly!

i am reading all these replies and i found them really interesting. i think
the same people being annoyed by sms-like writing, would get mad at me not
using proper casing with my sentences.

at the end of the day, i think it does not matter. i am not writing a book or
an article. and when i am texting, i would rather keep it short, sms-like.

i would like to understand, truly, why people get mad at such things. it has
nothing to do with being disrespectful or anything.

last time someone was mad at a particular emoji. i believe it's the next form
of shortening messages. and guess what? i would rather have an emoji than type
a sms-like message. maybe some of us just like being efficient?

~~~
NateEag
Emoji are a terrible insult to the written word. They're also an affront to
imagery.

Standard images, at least, are the same image everywhere. A grid of pixels is
a grid of pixels.

Emoji, however, vary from platform to platform, so what you pick may well not
be what your reader sees. In some cases that may matter, in others it may not.

Furthermore, some people construct new meanings and usages for emoji that do
not align with the actual descriptions from the Unicode standard. You'll only
realize this if they tell you, of course. I had one of those moments with my
wife a few weeks ago.

I'm still (irrationally) upset that emoji are in Unicode. They're ambiguous,
ill-defined, and they are certainly not characters in the multilingual support
sense of the word.

Do I use them? Yes, grudgingly, and I hate myself a little bit every time I do
it.

~~~
enriquto
Emoji are part of the natural oscillation of written language history between
ideographic and phonetic. It has happened several times in history, there's
nothing to worry about.

------
franciscop
I don't feel like it's undervalued; 93% of developers get frustrated by it:

\- [https://opensourcesurvey.org/2017/](https://opensourcesurvey.org/2017/)

It is a fairly thankless job because it's more difficult and the concept of
bugs or missing features is fairly fuzzy (compared to software). But it is
highly valuable, and people do notice it.

I attribute most of my open source popularity/stars at decent/good
docs+examples in my libraries, like the most recent one:

[https://github.com/franciscop/ola/](https://github.com/franciscop/ola/)

------
dsign
Why is this skill considered "undervalued"? Could it be attributed to the
gluttony of the industry for engineers? I have been in a couple of interviews
to job applicants who couldn't bother less to fix typos and grammar in the
first sentence of their CVs. The mere fact that we bothered to interview those
candidates is disturbing.

~~~
sam0x17
There are literally people who say "I hate verbal/writing stuff, I'll become
an engineer instead" during their undergraduate education, little knowing that
at least in industry these skills are critical.

------
xrd
Popular opinion almost makes it seem like "writing well" (for human
consumption) is almost the opposite of "writing good code" (for computers).

To be regarded as a great programmer, you need to know all the arcane details
of a system, where those are the intricacies of a particular language or
framework, or the small details of how a computer system works. It's the
minutiae that counts.

With writing for humans, you need to have a very high level overview of
things. You need to speak broadly and appeal to a common human understanding.
The top level understanding is what matters.

Coding interviews reflect the change the industry is sensing and what this
author puts well: the worst coding interviews are where they ask you about
some small detail of a language or algorithm. It's a gotcha test. The better
interviews ask you to show how you holistically approach a problem.

~~~
ragona
I disagree -- there are many situations in which your writing must display
both a very detailed understanding of a system, AND a very detailed
understanding of your audience.

~~~
thfuran
And, similarly, you can code perfectly functional code that properly handles
all the minutiae but is totally inconsistent with the general structure or
style of the project and that is bad. The high-level considerations are still
important there.

~~~
ragona
Agreed! The intersection of coding and communicating is really interesting.
That is my personal bar for a really phenomenal programmer — someone who can
produce code that communicates ideally to both humans and computers.

And this gets harder and harder depending on the task! It’s really tricky
stuff.

------
mattjaynes
Basically, here is what I tell myself when I'm going to write something for an
audience:

• Nobody gives a fuck ABOUT ME or how cool or awesome I am.

• People only care about how awesome THEY ARE.

• I am competing for their very short attention-span. Facebook, Netflix, and
porn are my competition. This better be pretty compelling if they are not
going to immediately hit their back button.

• I either need to address some real PAIN they have, or be pretty amazing at
entertaining them. In most cases, addressing a real pain is easier. It's much
harder to entertain better than porn, breaking news stories, etc.

• Structure for pain is clear:

1\. Identify the pain and show how much it hurts and costs them

2\. Show them the solution, and how good it will feel to stop losing and start
winning

3\. Anticipate and address their concerns. Are they worried about cost? Are
they worried about how much work it will require? Are they worried what their
boss or customers will think? Etc. Think of the most likely concerns or
objections they will have and explain how to resolve them. All or most of
their questions should be answered so that there is nothing in the way for the
next step...

4\. Call them to action to do something. Use your tool. Change a behavior.
Etc.

The structure can vary a bit, but this is generally the structure. In a purely
technical article, you may have very short sections on the pain, then spend
most of the time on the solution. If the purpose is more for sales, then
you'll want to have it more balanced and focus a lot on resolving concerns.

The article should be clear enough and structured enough so that every
paragraph can have a headline. And a reader should be able to scan the
headlines and know very quickly and clearly without having to think "what is
this article about?"

If the article feels or looks like work to read, they will give up right away
and you've lost them. There has to be something really compelling for them.
How will this make them more awesome? They don't give a fuck about anything
else.

They are milliseconds away from hitting their back button or searching for
"nude guitar solos", so put the effort in to deliver something compelling and
valuable. One well-thought-out clear useful article is far greater than a
hundred jumble-thought aimless ones.

Edit: formatting

------
kazinator
> _It is with a larger organisation that writing becomes important for
> messages to reach a wider group of people._

I'm not able to fully agree. An engineer is more likely to write text that
reaches a customer in its original form in a tiny startup or consulting firm
than in a big organization.

The larger the company, the more of a cog you are with specialized tasks.
Writing? That's a documentation person; just give them a rough draft capturing
all the info. Customers typically talk to customer support, not to you.
Customer support people have to write well, to be sure.

If the engineer started in a small organization which grew, but that
engineer's responsibilities grew in proportion also, then that is apples and
oranges. You have to compare how much writing is required in comparable roles.

------
dkarl
I think people appreciate this about other people, so if there's a place where
it is undervalued, it's when people evaluate themselves and their
opportunities for improvement.

I remember Bjarne Stroustrup saying that an important sign that a person could
become a good programmer was that they could write clearly in their native
(natural) language. I can't find that quote, but I did find a 2013 interview
[1] in which, forced to pick three key pieces of advice for budding
programmers in their early twenties, his #2 was, "Learn to communicate well,
verbally and in writing."

[1] [https://yourstory.com/2013/12/bjarne-stroustrup-
interview](https://yourstory.com/2013/12/bjarne-stroustrup-interview)

------
growlist
Agreed, hugely undervalued and I would argue pretty rare. My formal grammar is
pretty poor and I mainly operate on what sounds right, but nonetheless I am
commonly shocked by the basic mistakes that are made by most people including
very senior people - poor punctuation, ambiguities, misuse of apostrophes etc.
I don't know if this says something about education in the UK? But the main
message to me is - things other than writing matter when it comes to getting
ahead. Why bother showing it off or improving when it will likely just get you
labelled as (if you can believe this still happens in a business like tech -
but it does) a geek.

------
soneca
This article pitches the idea that writing is an important skill to advance
your _career_. It makes the point that you will be better at spreading an idea
and influencing people.

I agree with this, but to me personally, the more compelling reason to improve
your writing is that will improve your _work_ (not necessarily your career).

It is more about better communication than influencing people. I want people
to more easily and reliably understand what I am trying to communicate.
Understand my ideas, my doubts, my suggestions, my attitude, my feelings.

My writing was definitely valuable in my transition to software development
two years ago.

------
nihil75
Why is it undervalued? because you decided it's so? It's extremely valued, and
even specified as a requirement for most positions (either explicitly or under
"communication skills").

~~~
munificent
It's undervalued if you observe the amount of deliberate effort most engineers
put into improving that skill compared to the benefits they would garner from
doing so.

------
cosmodisk
I think writing doesn't get anywhere near the attention ot should be
getting.I've met and I work with some really great people but boy oh boy they
struggle to write.I'm not talking about producing the next bestseller but
simply communicating simple ideas. I read what some of them write I think:
wtf...if you were only able to write better you could be reaching the sky..
Technical capabilities+ ability to communicate well in writing is a killer
skill and can literally elevate people to a whole new level..

------
mrmrcoleman
Fully agree and I'd expand the point to cover communication in general.
Explaining ideas clearly with text or voice is one of the characteristics that
I've noticed in high-functioning engineering teams.

I did a talk[1] a few years back about my experiences helping a team to
improve their communication skills. What surprised me was the emotional
complications that prevent people from communicating effectively.

[1] [https://vimeo.com/134601419](https://vimeo.com/134601419)

~~~
sandGorgon
Is there are tutorials or training material you would recommend. I have been
hearing "plain writing" more and more...but not sure if it is the right thing.

~~~
mrmrcoleman
I’m sorry I don’t have any link to hand that would help with writing.

------
mlthoughts2018
I actually have found that if you are an engineer who displays well-rounded
skills in multiple disciplines, like business acumen, communication, writing
and conflict management, this causes managers and non-engineers around you to
view you as a threat, and they will work harder to undermine you and try to
box you into a “engineer only” label.

Above all, you won’t be rewarded for these other skills, despite how vital
they are.

~~~
beat
Ugh. In that case, you should move to someplace that values those skills.

~~~
mlthoughts2018
It has been this way at every job (7 companies now, ranging from huge &
bureaucratic to medium & popular to super new start-up). Whether it has been
at a major tech company or the latest & greatest start-up, people have
universally acted this way everywhere, often while talking at length about how
their company culture causes them to not act this way.

------
siculars
I say it all the time: a significant fraction of my job is to read and write
google documents. I’m either writing docs or I’m reading/commenting on docs
someone else wrote.

Reading and writing are foundational skills needed in virtually every field.
Especially especially especially at google.

/I work at google/

------
jacquesm
Funny, I _never_ thought that that would be the hill one of my plans would die
on. Writing well - and reasonably quick - is rare, when you take the
intersection of people that have that skill with people that are technically
inclined the resulting set is super small.

------
amirhirsch
Did anyone else find this article to consist of ironically poor writing? The
blog post contains of a lot of fragments, run-on-sentences, unnecessary
pauses, mixed tenses, dangling clauses, use of the passive voices, and no
Oxford comma!

~~~
d23
I'm surprised this is so far down. I'm assuming most people commenting didn't
actually read it and are just agreeing with the sentiment.

Perhaps the author is not a native language speaker? That being said, I'm not
sure why you'd write an article about the importance of writing if your
writing is... below average at best.

~~~
amirhirsch
I was late to the party so the general conversation seems to have taken a
different direction, but glad I'm not alone.

------
Envec83
I completely agree. In fact I created
[https://www.dailywritingtips.com/](https://www.dailywritingtips.com/) (more
than 10 years ago) for this exact reason.

------
ericmcer
There are kinda two disciplines here, writing something that tries to convey a
complex concept is important, but it's also important to be able to tersely
describe a problem, and use correct, agreed upon language to do it.

Compare:

Wrong error message shows on Xm-z pages username input.

Xm-z page, username input, Error message incorrect.

I would argue that having agreed upon naming, and explicit syntax for how to
describe issues/improvements in-between your team members is almost more
important than being a good writer. The bottom sentence isn't even
grammatically correct.

------
lgleason
As an engineer and now an author of a technical book I definitely agree with
this. I have seen many places where they have a talented engineering team that
cannot communicate what they have created etc. to everybody else. The worse
anti-pattern is when they hire technical writers with no knowledge of the
domain (or dev skills) to create documentation on how to use API's targeted at
developers... The end documentation from that effort, unsurprisingly, is often
borderline incomprehensible.

------
petra
What about using writing to sell an idea ?

My friend, who isn't good at interpersonal skills, is trying that.

Can this work for him ? or is the trust created via face-to-face is
irreplaceable for convincing others ?

~~~
uberstuber
If anything, good writing is more persuasive than face-to-face. A well written
document carries some gravitas.

Of course, you have to get decision makers to read it...

------
jcaprani
Is anyone else seeing the irony of the poor writing in this article?

~~~
_hardwaregeek
In fairness, the author is not a native English speaker. And he makes his
point with clarity and cohesion. There are some awkward phrases, but by
engineering standards his writing is perfectly fine :D

------
joshuacc
Along these lines, I have a half-completed book on GitHub titled Prose for
Programmers: [https://github.com/joshuacc/prose-for-
programmers](https://github.com/joshuacc/prose-for-programmers)

I started it because I found that being able to write effectively was my
biggest advantage at work. Compared to others who were at least as technically
competent as myself, I was more often able to persuade others to take the
course of action I prefer.

------
everyone
I think writing well is a skill that is in very short supply all around, even
in writing-focused areas like journalism. A major culprit in this, in my
opinion, is how writing is taught in college. It's very common for students to
be tasked with writing an essay with a _minimum_ word count. This has been
training people into the habit of being unnecessarily wordy and obtuse. What
they should do, is give students a higher mark the _less_ words they use to
make their point.

~~~
necovek
You overestimate people's ability and enjoyment in reading concise writing
that has each word measured carefully.

In order to pass an exam in university, I had to deliberately repeat myself in
a few subtle ways, only to be commended how I managed to get my points across
very concisely.

I find that writing well is somewhere in the middle: people are used to skip-
reading, so being very concise is counter-productive: unless you want to
repeatedly point them to actual bits of text that answer their question but
which they probably went over as only fill-text.

So, I prefer to state my position concisely at the front, benefitting people
like me who prefer it that way, and then expand it with examples and more
elaborate arguments for those that need more.

Like this post: the whole point is in the first sentence. The rest is just for
the majority who'd basically not even read it, let alone bother to understand
it.

(As a consequence, I often miss the happy middle and become too elaborate:
it's a struggle :))

------
hwj
For German speakers:

there's a good book about writing in computer science called "Technisches
Schreiben (nicht nur) für Informatiker"[1].

The appendeix contains a funny correspondence between an author and his
publisher whether "FORTRAN" or "Fontran" is correct.

[1]: [https://www.hanser-
fachbuch.de/buch/Technisches+Schreiben/97...](https://www.hanser-
fachbuch.de/buch/Technisches+Schreiben/9783446409576)

------
hbarka
In the US university system there are undergraduate requirements called
distributional or general education requirements. The breadth of the courses
cover humanities and arts, social sciences, and other classes under a Liberal
Arts category. I wonder if there are similar requirements in other countries.
Does an undergrad degree, say in India, have an apples-to-apples equivalent to
an undergrad in the US with respect to the distributional requirement.

------
mailslot
This is literally how I get “impossible” changes to happen virtually anywhere.
There’s so much psychology that goes into the impact of the written word.

Don’t spread my secret. :(

------
inflatableDodo
Writing well? I've had to read engineering drawings for QC in a precision
engineering shop working with critical industries. Screw grammar and style
being undervalued. You get told to fuck off if you complain about spelling.

edit - there is a pathological aversion to updating a drawing, not because of
the work, but because of the process. People will do almost anything to avoid
having to get an update signed off.

~~~
sixstringtheory
Assuming QC == quality control, I find that attitude highly ironic.

Measure twice, cut once. Take the time to write carefully up front and
proofread, before you submit it to a lengthy process.

~~~
inflatableDodo
I think a lot of people doing the drawings are either dyslexic, or maybe just
do not care. Also, engineering companies don't tend to have proofreaders. I
can proofread, but learned quickly that I should not bother proofreading the
drawings that came through. All it ever achieved was a torrent of abuse,
combined with a flat refusal to even think about getting a new drawing issued.

------
spurcell93
This is one thing I love about stripe. There are a ton of resources to write,
and every employee is encouraged to communicate at a very high level.

------
ragona
This falls into the category of a much wider undervalued engineering skill --
communicating well. The best engineers tend to be excellent communicators.
There is a whole group of extremely talented programmers who just don't
understand why they aren't getting ahead, and nine times out of ten the answer
is that they suck at communicating.

------
piaromba
I recall my technical writing class in collage was actually pretty good and it
was a required course. But when i went into industry there was not monetary
connection to writing quality. Sometimes it is even better for developers to
have convoluted documentation because then they make themselves indispensable
to maintenance in the future.

~~~
pickle-wizard
I too took a technical writing class in college and it was very helpful.

I used to be a pretty good technical writer early in my career. Everything I
did was documented throughly. Anyone could read my documentation and pick up
the project.

Then we had a management change. I would literally get yelled at by my
director because I was wasting time creating documentation. So I stopped.
Didn't document shit, and the yelling stopped.

I'm at a new job now, and I'm trying to get back in the habit of documenting
everything. Though those skills are very rusty.

------
michaelmior
I recently had a colleague recommend Writing for Computer Science[0]. It feels
targeted more toward academics, but there's plenty of useful things in there.

[0]
[https://www.springer.com/us/book/9781447166382](https://www.springer.com/us/book/9781447166382)

------
tmaly
I would highly recommend the book The Pyramid Principle for improving your
writing in a professional environment.

------
fooblitzky
Another undervalued skill is speaking well. Since joining Toastmasters my
career has undergone a step change. Managers perceive me as being much more
effective, even though my writing and coding skills have only continued
growing incrementally. It's the best investment of time I've ever made.

------
eutropia
I sometimes think that programmers come in two types: mathematically inclined
or linguistically inclined. Think sorting vs parsing.

I only realized this after testing out of and skipping all English and writing
requirements easily, but having to retake several mathematics courses during
my time in engineering school.

------
dano
I recommend the following book on a regular basis to those in newly minted
leadership positions.

[https://www.amazon.com/Writing-Works-Communicate-
Effectively...](https://www.amazon.com/Writing-Works-Communicate-Effectively-
Business/dp/0060956437/)

------
heisenbit
In the Middle Age we needed to thumb through huge binders located in a room
close to the mainframe. Tedious.

Then we could buy the books. We still needed to thumb through and it took
time.

The the wastage of engineering hours was decreased by putting the writing to
low level engineers. That was a good idea as it saved money.

That idea could be made even better by having documentation moved to another
location by even lower paid staff. Great financial results!

In the meanwhile we got patterns and realized that all software is created the
same. Documentation can be recycled and continuous releasing saves time for
unneeded reviews.

Software and its documentation is really just assembling blocks. Learning from
the leader in that space, Ikea's manuals yielded even greater results. And
with additional ingenuity video was introduced. Saves trees, Ikea could learn
from us.

These days one does not need to read much anymore, just google a video. And if
a problem can't be solved, then agility comes to rescue. Lean development
means problems are solved when needed and that is what agile users are for.

~~~
m_fayer
I'm not totally sure what you're doing here, but I like it.

------
ironman1478
At USC, they had multiple mandatory writing classes and I felt that the people
who did well in those classes did well in engineering too. I think there is a
high correlation between being able to clearly write something down and
explain it and understanding the concepts.

------
zn44
This article comes at a perfect time. As I want to work on my writing skills.
I’ve found many recommendations in this thread on how to improve your skills
but nothing focusing on technical writing.

Any recommendations for materials specifically for developers?

------
jambutters
[https://youtu.be/vtIzMaLkCaM](https://youtu.be/vtIzMaLkCaM) has very
interesting tips on writing.

tl;dw : you have been taught to write to people(teachers) who are paid to care
about your writing.

------
tw1010
Ugh, I don't understand why people keep recommend the Pinker book about
writing well. Pinker has the most formal god awful style I could imagine.
There are so many better writers to learn from. Don't fall for mimetics guys.

~~~
criddell
Can you be more specific? I started reading it and I'm actually enjoying
reading about writing.

------
jestinjoy1
I am from India and here writing skill for engineers is not valued at all. As
someone into research, I found it important when I started sending papers.
Academia here is not giving importance to the writing of its students.

------
kinkajou
I've been interested improving my technical writing for some time but don't
really have any idea what good tech writing looks like.

Can someone suggest some examples of what you consider really good documents?

------
pugworthy
The ability to be "agile" with writing is pretty important to some. I
sometimes find I'll edit and revise (and tweak) a gamedev stack post many,
many times over just little things.

------
jlmorton
> I have noticed a few skills that people often underestimate the importance
> of developing. Skills that add a significant boost to the impact of any
> developer. _One of these ones is writing._

Heh.

------
bearcobra
One thing I love to do is send any major communication I've written through
text to speech. I've caught soo many mistakes that Grammarly or Word didn't
when I hear it.

------
keitsist
I know this is an off topic question but would anyone know of a similar
site/author with a electrical and/or mechanical engineering focus/background?

------
Myrmornis
I agree that writing well is extremely important. However people like to do so
much verbally in meetings, that what you write will probably not be read
carefully.

------
abbadadda
"One of these ones is writing." \- I couldn't help but laugh at this. Would
have been a little more concise to drop the "ones."

------
sam0x17
Right up there with "communicating well", and the often important "managing
the expectations of non-technical stakeholders"

------
syndacks
I'm surprised this article doesn't suggest reading books. The best way to
improve your writing is to read good writing.

------
JustSomeNobody
I get that times are changing, but I still believe that if you choose not to
write well, you just aren't being professional.

------
0xdeadbeefbabe
Reading is undervalued, and just writing better won't fix it.

Good readers tend to underestimate this problem obviously. If you read the
article I bet your colleague didn't, and he or she isn't interested in reading
your better-catchy-succinct-effective-if-not-superlative writing either, and
he or she is going to rewrite the system.

(Oh but exceptions I can think of are Harry Potter, and also the LKML as a
vehicle for developing linux)

------
antpls
I totally disagree with this claim, because, it is discriminating, narrow-
minded, shortsighted and subjective.

Writing is only a way to convey information, there a many other ways to do it,
and there surely will be other ways.

The current system favors people who know how to write in English, but it
doesn't mean it's fair nor right.

A language that may work for you may not work for others, therefore, "well" is
not objective.

~~~
duckmysick
> Writing is only a way to convey information, there a many other ways to do
> it, and there surely will be other ways.

It's the best way of conveying information, especially in a business setting.
It's accessible, portable, can be as detailed and nuanced as needed, you can
copy it, you can reference it later, you don't need a proprietary solution to
use it. In fact, you don't even need a computer for it. All other methods of
conveying information in a business setting that I can think of (face-to-face
communication, video and audio conferences, Power Point presentations, chat
apps, symbols, source code) don't meet all of the above criteria.

> The current system favors people who know how to write in English

Now this is discriminating and narrow-minded. Nothing stops a German company
from writing well in German - if that's their main language.

I'm curious which system you think is more fair and objective.

> A language that may work for you may not work for others

This could be generalized as "a _solution_ that may work for you may not work
for others". And that's ok. An organization can have its own culture. A part
of this culture might be writing well, but also agile, open floor plan,
working remotely, or afternoon mimosas. It's ok to disagree with the culture
of a particular company and not be a good fit. You are free to prefer
companies that don't emphasize good writing skills - which I suspect are the
majority.

------
ulisesrmzroche
Engineers should write more science fiction, especially software engineers.

I’ve already died on this hill tho.

------
peter_retief
Good software skills are good writing skills

------
now
”Writing Good”, there, I fixed it for you.

------
zadkey
Also, documentation skills.

------
dboreham
See also: critical thinking

~~~
pistachios
What is a good book on this subject?

------
vidro3
second only to reading comprehension

------
starpilot
how too rite good?i dum dum

------
bongobongo
I don't think this and other so-called "soft" skills are undervalued by
engineers themselves. A good writer/communicator brings immediate value to any
engineering team and will be treated as such, usually. It's the pointy heads
and the business side of the operation who don't value it, because it's not
sexy. IT and software engineering are abstract to them, so when they don't see
"hands on keyboards" (writing code), they think no work is being done.

Software engineering will remain in its infancy as a "profession" until
software engineers themselves organize and better assert their own
professional standards. Writing and iterating over documentation is an ISO
standard that is ignored 99% of the time. If you ignore your professional
standards, you are not a professional, no matter your title or your salary or
even your field of work.

------
adamnemecek
It's hardly undervalued. Another one mentioned too much is "empathy".

I feel like these are such softball answers, as no one will say no, this is
bullshit.

~~~
stronglikedan
It's definitely undervalued by engineers themselves. I.e., the majority don't
seem to treat this skill as a priority in their professional development.
However, it's definitely not undervalued by the companies that hire them.
Especially as they progress through their careers, where they will experience
a glass-ceiling affect if they have not sharpened that skill.

EDIT: Fixed stupid autocorrect error (thanks sokoloff). I wish browser inputs
had grammar hints as well as spelling correction.

~~~
sanderjd
I think this is true inside a company, but it is another example of how weird
our hiring techniques are. Writing plays basically no part in the hiring
process. So for those engineers who have progressed by sharpening that skill,
it is jarring to find that the barrier to their next job takes absolutely no
account of it. You can spend years impacting or entirely setting the technical
direction of a project or entire company through your writing (and verbal
communication as well), and then find that all you're asked during your
interview for your next job is to solve some made up problem using code on a
whiteboard. It's bizarre.

~~~
sokoloff
Your comment made me realize that even when we hire execs/senior execs, I
can't recall ever specifically evaluating their writing skills. I only recall
doing so for dedicated comms people, but it's just as relevant for execs and
yet we don't seem to do it there either.

