8 ms·

Superior writing skills are one of two things that separate novice developers from experts. This, as judged from experience, is self-evident to all people excep

Superior writing skills are one of two things that separate novice developers from experts. This, as judged from experience, is self-evident to all people except bad developers. Here are the criteria that are generally most important: * precision: This is perhaps most important. The ability to communicate tiny finite details that immediately reflects the product as a whole in a way that is universally clear to a wide audience in the same way is paramount. * directness: Say what you mean. Don’t waste people’s time with distractions and pleasantries. Put the most important things first. If the audience wishes to read more they will. * conciseness: There is an art to the careful description of technical details, behaviors, and examination of a subject that is both precise and still expressed in the fewest words/statements. An extended vocabulary is helpful. * organization: Almost everything complex is open to more simplistic description as a subject of intrinsic relationships. The ability to perceive, understand, and convey those relationships is logic at its most base foundation but only when the those relationships are orderly and supported by evidence. A common mistake is to be clever about organization, relationships, and their logic. Don’t do that. People do this as a weak form of manipulation, but strong communicators will tear it apart. All of these points on writing are directly evident in well written code as well as formally expressed writings for general audiences.

dfsegoat 7y ago
> Superior writing skills are one of two things that separate novice developers from experts. This has been an area of concern for me. As I've increased my technical skills, I feel like my writing skills have atrophied, which impacts communication with my team and management. As such, I found these tips very helpful.
- austincheney 7y ago
  I think a common mistake many developers, or any early writer in other disciplines, make is not reflecting on this as you are. Knowing and accepting this as a personal weakness puts you ahead of your peers who may have a similar weakness.
heinrichhartman 7y ago
Great list. Let me add a few things: * Ad Precision/Conciseness: When crossing disciplines from Math => Software, this annoyed me to no end: I was not able to express myself concisely. I found that vocabulary is a large part of this, I knew what I meant but did not have the words for it. This is stuff like: call site. caller callee. function signature. deployment vs. installation vs. release Also you need good words to describe the objects/systems that you are building, and the domain your are operating in. This is why NAMING things is so critical. You need to have good words for the concepts you are working with. * Ad Directness: Yes. But try to avoid value judgements and insults. Stay objective: "This code is shit!" vs. "I don't think the case X==0 is handled correctly."
- abnry 7y ago
  For the developers in the comments, having a better vocabulary is like having a better standard library. If you have to describe the details of a basic data structure every time you bring it up, you will lose the audience. The psychological concept of chunking plays an important role here. By encapsulating a complicated concept into a single package you increase comprehension and the ability to reason. There is the same thing in mathematics where coming up with definitions (standard library functions) are crucial. One of the biggest developments in calculus was a rigorous definition of continuity. The definition itself is complicated. However, once you encapsulate the entire concept into the single word "continuity," you can start exploring and proving many more theorems.
- KineticLensman 7y ago
  > you need good words to describe the objects/systems that you are building Totally agree! And I would add, once you have come up with a word (or label), stick with it. There is nothing worse, in technical writing, than an author who keeps using different terms for the same thing in a single document. It leaves the reader with the task of keeping track of what is being described, and thus makes the doc harder to read. I think there are several reasons for this: * authors showing off their extensive vocabulary * authors trying to add novelty by using new synonyms * authors who haven't checked other parts of the doc to see what was said elsewhere. In technical writing, the author's job is to communicate as consistently as possible to reduce the cognitive burden on the reader.
Tepix 7y ago
Developers who are good writers are just a small subset of writers. There are other skills in demand for writers in different areas. For example if a developer were to fullfil all the criteria you listed, the result could still be extremely boring and dull for the general audience you mention.
- k__ 7y ago
  Yes. I haven't met a single senior dev in person that could write good.
  - asdffdsa 7y ago
    well
bradstewart 7y ago
So much this. Calls to mind one of my favorite quotes (one of the few specific things I remember from high school actually): “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.” ― William Strunk Jr., The Elements of Style Precise writing is absolutely critical for communicating complex ideas, yet rarely at the front of people's minds (at least in the software world). I feel like the move to Slack and other chat apps has made the problem worse.
- morelisp 7y ago
  As so often is the case when quoting Strunk, he violates his own rules. "Vigorous writing is concise and should contain no unnecessary words or sentences. But the goal is not conciseness per se, rather that every word tell." The analogy with machines unnecessary; the analogy with drawing incorrect; the hypothetical writer a distraction. And yet, it's not as forceful. Maybe he's just plain wrong?
  - deleted 7y ago
    [deleted]
  - zxcmx 7y ago
    Since the extra words express the point more forcefully, perhaps they were necessary after all :p
  - bradstewart 7y ago
    There's certainly no hard and fast rule here. Much is left to the opinions of the author. I'd argue that the analogy is necessary--it adds force to the argument, as you note. Assuming the point of his statement is to convince the reader of something. Side note: solid use of the semicolon there.
    - morelisp 7y ago
lhorie 7y ago
> conciseness There's also an important nuance here: clarity. Many times re-reading something I've written, I realized that I was being concise, but at the expense of clarity, by using jargon without explaining it. One needs to be careful not to be too concise, or they risk going over the reader's head.
- gozzoo 7y ago
  I think clarity is more important than conciseness. Furthermore, sometimes when explainng a complex topic I find myself being deliberately too verbose. I try to provide more context, like giving examples, anecdotes, explaing the same concept from different points of view, exploring contradicting ideas, etc. good writing != concise writing
- john-tells-all 7y ago
  I agree! Often my writing is too short: I know what I mean in my head, but the ideas don't translate to the words on the page. My friend gave me great advice: he asked "hey can you unpack that for me?" -- my text was too concise and not clear.
BurningFrog 7y ago
Also, though many developers don't even realize it, writing code is storytelling for human code readers.
- lloeki 7y ago
  > Programs must be written for people to read, and only incidentally for machines to execute. - Harold Abelson
snowwrestler 7y ago
Here's the "one weird tip" life hack to do all of these things: revise and rewrite. Important communications should go through multiple drafts. That includes important emails. Write it all out, then re-read it carefully, ideally after a bit of time has passed. Edit with an eye toward making it shorter. Rewrite it from scratch if you have to. I once had the good fortune to take a writing class with Edward Hoagland. We spent most of the semester with each student working on a single essay--reviewing it, editing it, rewriting it, rewriting it.
- frostwhale 7y ago
  As someone who had issues with this before, can second this is the best advice. As well as running it by someone else to see if they're picking up on the narrative you're trying to convey.
- Tade0 7y ago
  > Write it all out, then re-read it carefully, ideally after a bit of time has passed. Edit with an eye toward making it shorter. Rewrite it from scratch if you have to. That's what I've been doing. I'm not an amazing developer, but with time and effort I am able to refactor my way to decent code. Forgetfulness has been my ally - if you forget about something you're obviously not attached to it, so it's easier to throw it out and replace with something better.
- ocdtrekkie 7y ago
  My last writing professor didn't have a Wikipedia page, but he was fantastic, and taught with an approach on iteration: He allowed us to submit our assignments for review, and then let us take back the paper to work on it more, and we could continue to do that until it was an A paper. This essentially guaranteed everyone an A in the course, if they did the work. But the focus was on getting you to improve your writing, not to fail people out. My opinion is that this is how writing should be taught, rather than giving you one shot to get a grade. (I also once had a writing teacher who gave me a zero for a paper because it wasn't submitted in a manilla folder, and no late submissions were accepted, so I had no chance to fix it.)
  - 7y ago
dandare 7y ago
This is sucha priviledget statement. Writing skills depend a lot on the brain predisposition you were lucky to be born with. (Actually like almost any other skills ;). ) As a partial dislectic (it comes in circles) the biggest challenge in my career is my communication skill. There are day when I spend 3x time to write a compelling sentence. I am envy of all the C leve psychopaths that can hash any negative announcement in a full page email, full of inclusion, praise, buzzwords and more pulp. Good communication skills are super useful but loosely correlated with knowledge or dedication.
- gozzoo 7y ago
  > C leve psychopaths I like this expression. Your dyslexia didn't hinder your ability to come up with such original metaphor. Elon Musk is a good example of that. I mean his writing of course :)
matwood 7y ago
I completely agree that writing skills are paramount to grow as a developer and beyond. While I agree there is no reason to wax poetic in an email, I find that normal professional pleasantries help the communication process.
2OEH8eoCRo0 7y ago
Could you recommend a good book or resource that covers these topics?
- filipsch 7y ago
  “On Writing Well” by William Zinsser is a title that covers some items on the list, although it’s general for writing non-fiction. It taught me to get rid of the fluff in sentences to make my writing more compelling.
  - 2OEH8eoCRo0 7y ago
    Thank you for the suggestion. I will check it out.
danenania 7y ago
That’s a great list! One thing I would add is empathy. There seem to be a lot of great engineers who are also strong communicators, but still struggle with this. For example, if someone encounters a problem when running or integrating code you’ve written, you will almost always get to the heart of the problem more efficiently and with less negative emotion if you start by demonstrating that you empathize with that person’s frustration. That’s true even if the issue ends up being something on their side of the line. Acting defensive in these situations is natural, especially if you feel that anger is being directed at you unfairly, but it tends to just get in the way of finding a solution.
- john-tells-all 7y ago
  Absolutely. It's incredibly easy to be a condescending engineer, thus sabotaging yourself and your ideas. Practicing empathy is a tremendous benefit to yourself and your team! Esther Nam clearly explained this: https://www.youtube.com/watch?v=IYWlfVqBQLc https://www.youtube.com/watch?v=IYWlfVqBQLc
  - john4534243 7y ago
    In my opinion anyone who does not have verifiable proof for their technical competency is not worth the time listening to their talk. I am not saying they don't have valid points but its too much of an ask.
WalterBright 7y ago
Like, I totally agree. Frankly, you're so right. Know what I mean? People really write too many words, basically, to say something they could express quite readily in far fewer words. Man, sentences go on and on saying the same thing over and over. I'll be honest, this is wearying and tiresome to read. Can't people simplify and get to the point? Do people even bother to read what they write? Too be perfectly honest, this is tiresome and tedious.
- austincheney 7y ago
  It's not just the written word. The same applies to the spoken word as well. When people in the military ask me how to improve their spoken word I tell them to focus only on rhythm and otherwise regard their content as sewage. Once the word is flushed from your mouth you cannot have it back. If the sewage (speech) stops flowing unintentionally the system backs up and cognitive problems take over, so keep pushing words out at a regular pace. That regular pace will eliminate the need for gap words like: uh, um, and ah. The content of the sewage is generally less important than the audience's reaction, so always be ready to pivot without causing a sewage backup.
  - WalterBright 7y ago
    When people start a sentence with "I'll be honest with you" I'll often rudely interrupt saying "you mean you weren't honest before?" Yes, I know it is a meaningless filler phrase. I got tired of watching "American Chopper" partly because the son started every sentence with that phrase. A colleague basically of mine basically interjected "basically" between basically every couple basically of words, basically. So I basically started basically writing basically a lot of "basically" interjections basically in my basically emails basically to basically him. Fortunately, he basically had basically a great basically sense of basically humor. Like, totally.
    - austincheney 7y ago
      My favorite phrase to use in these situations is to use this as a compliment: It could be worse. It seems contrary to agree with as though the topic is horrible, but disagreement means the topic is the worst. It forces a moment of self reflection and then people suddenly become aware of the words spoken.
invisiblerobot 7y ago
Well written. Two excellent books are The Elements of Style and On Writing Well.

dfsegoat 7y ago

> Superior writing skills are one of two things that separate novice developers from experts. This has been an area of concern for me. As I've increased my technical skills, I feel like my writing skills have atrophied, which impacts communication with my team and management. As such, I found these tips very helpful.

austincheney 7y ago
I think a common mistake many developers, or any early writer in other disciplines, make is not reflecting on this as you are. Knowing and accepting this as a personal weakness puts you ahead of your peers who may have a similar weakness.

heinrichhartman 7y ago

Great list. Let me add a few things: * Ad Precision/Conciseness: When crossing disciplines from Math => Software, this annoyed me to no end: I was not able to express myself concisely. I found that vocabulary is a large part of this, I knew what I meant but did not have the words for it. This is stuff like: call site. caller callee. function signature. deployment vs. installation vs. release Also you need good words to describe the objects/systems that you are building, and the domain your are operating in. This is why NAMING things is so critical. You need to have good words for the concepts you are working with. * Ad Directness: Yes. But try to avoid value judgements and insults. Stay objective: "This code is shit!" vs. "I don't think the case X==0 is handled correctly."

abnry 7y ago
For the developers in the comments, having a better vocabulary is like having a better standard library. If you have to describe the details of a basic data structure every time you bring it up, you will lose the audience. The psychological concept of chunking plays an important role here. By encapsulating a complicated concept into a single package you increase comprehension and the ability to reason. There is the same thing in mathematics where coming up with definitions (standard library functions) are crucial. One of the biggest developments in calculus was a rigorous definition of continuity. The definition itself is complicated. However, once you encapsulate the entire concept into the single word "continuity," you can start exploring and proving many more theorems.
KineticLensman 7y ago
> you need good words to describe the objects/systems that you are building Totally agree! And I would add, once you have come up with a word (or label), stick with it. There is nothing worse, in technical writing, than an author who keeps using different terms for the same thing in a single document. It leaves the reader with the task of keeping track of what is being described, and thus makes the doc harder to read. I think there are several reasons for this: * authors showing off their extensive vocabulary * authors trying to add novelty by using new synonyms * authors who haven't checked other parts of the doc to see what was said elsewhere. In technical writing, the author's job is to communicate as consistently as possible to reduce the cognitive burden on the reader.

Tepix 7y ago

Developers who are good writers are just a small subset of writers. There are other skills in demand for writers in different areas. For example if a developer were to fullfil all the criteria you listed, the result could still be extremely boring and dull for the general audience you mention.

k__ 7y ago
Yes. I haven't met a single senior dev in person that could write good.
- asdffdsa 7y ago
  well

bradstewart 7y ago

So much this. Calls to mind one of my favorite quotes (one of the few specific things I remember from high school actually): “Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.” ― William Strunk Jr., The Elements of Style Precise writing is absolutely critical for communicating complex ideas, yet rarely at the front of people's minds (at least in the software world). I feel like the move to Slack and other chat apps has made the problem worse.

morelisp 7y ago
As so often is the case when quoting Strunk, he violates his own rules. "Vigorous writing is concise and should contain no unnecessary words or sentences. But the goal is not conciseness per se, rather that every word tell." The analogy with machines unnecessary; the analogy with drawing incorrect; the hypothetical writer a distraction. And yet, it's not as forceful. Maybe he's just plain wrong?
- deleted 7y ago
  [deleted]
- zxcmx 7y ago
  Since the extra words express the point more forcefully, perhaps they were necessary after all :p
- bradstewart 7y ago
  There's certainly no hard and fast rule here. Much is left to the opinions of the author. I'd argue that the analogy is necessary--it adds force to the argument, as you note. Assuming the point of his statement is to convince the reader of something. Side note: solid use of the semicolon there.
  - morelisp 7y ago

lhorie 7y ago

> conciseness There's also an important nuance here: clarity. Many times re-reading something I've written, I realized that I was being concise, but at the expense of clarity, by using jargon without explaining it. One needs to be careful not to be too concise, or they risk going over the reader's head.

gozzoo 7y ago
I think clarity is more important than conciseness. Furthermore, sometimes when explainng a complex topic I find myself being deliberately too verbose. I try to provide more context, like giving examples, anecdotes, explaing the same concept from different points of view, exploring contradicting ideas, etc. good writing != concise writing
john-tells-all 7y ago
I agree! Often my writing is too short: I know what I mean in my head, but the ideas don't translate to the words on the page. My friend gave me great advice: he asked "hey can you unpack that for me?" -- my text was too concise and not clear.

BurningFrog 7y ago

Also, though many developers don't even realize it, writing code is storytelling for human code readers.

lloeki 7y ago
> Programs must be written for people to read, and only incidentally for machines to execute. - Harold Abelson

snowwrestler 7y ago

Here's the "one weird tip" life hack to do all of these things: revise and rewrite. Important communications should go through multiple drafts. That includes important emails. Write it all out, then re-read it carefully, ideally after a bit of time has passed. Edit with an eye toward making it shorter. Rewrite it from scratch if you have to. I once had the good fortune to take a writing class with Edward Hoagland. We spent most of the semester with each student working on a single essay--reviewing it, editing it, rewriting it, rewriting it.

frostwhale 7y ago
As someone who had issues with this before, can second this is the best advice. As well as running it by someone else to see if they're picking up on the narrative you're trying to convey.
Tade0 7y ago
> Write it all out, then re-read it carefully, ideally after a bit of time has passed. Edit with an eye toward making it shorter. Rewrite it from scratch if you have to. That's what I've been doing. I'm not an amazing developer, but with time and effort I am able to refactor my way to decent code. Forgetfulness has been my ally - if you forget about something you're obviously not attached to it, so it's easier to throw it out and replace with something better.
ocdtrekkie 7y ago
My last writing professor didn't have a Wikipedia page, but he was fantastic, and taught with an approach on iteration: He allowed us to submit our assignments for review, and then let us take back the paper to work on it more, and we could continue to do that until it was an A paper. This essentially guaranteed everyone an A in the course, if they did the work. But the focus was on getting you to improve your writing, not to fail people out. My opinion is that this is how writing should be taught, rather than giving you one shot to get a grade. (I also once had a writing teacher who gave me a zero for a paper because it wasn't submitted in a manilla folder, and no late submissions were accepted, so I had no chance to fix it.)
- 7y ago

dandare 7y ago

This is sucha priviledget statement. Writing skills depend a lot on the brain predisposition you were lucky to be born with. (Actually like almost any other skills ;). ) As a partial dislectic (it comes in circles) the biggest challenge in my career is my communication skill. There are day when I spend 3x time to write a compelling sentence. I am envy of all the C leve psychopaths that can hash any negative announcement in a full page email, full of inclusion, praise, buzzwords and more pulp. Good communication skills are super useful but loosely correlated with knowledge or dedication.

gozzoo 7y ago
> C leve psychopaths I like this expression. Your dyslexia didn't hinder your ability to come up with such original metaphor. Elon Musk is a good example of that. I mean his writing of course :)

matwood 7y ago

I completely agree that writing skills are paramount to grow as a developer and beyond. While I agree there is no reason to wax poetic in an email, I find that normal professional pleasantries help the communication process.

2OEH8eoCRo0 7y ago

Could you recommend a good book or resource that covers these topics?

filipsch 7y ago
“On Writing Well” by William Zinsser is a title that covers some items on the list, although it’s general for writing non-fiction. It taught me to get rid of the fluff in sentences to make my writing more compelling.
- 2OEH8eoCRo0 7y ago
  Thank you for the suggestion. I will check it out.

danenania 7y ago

That’s a great list! One thing I would add is empathy. There seem to be a lot of great engineers who are also strong communicators, but still struggle with this. For example, if someone encounters a problem when running or integrating code you’ve written, you will almost always get to the heart of the problem more efficiently and with less negative emotion if you start by demonstrating that you empathize with that person’s frustration. That’s true even if the issue ends up being something on their side of the line. Acting defensive in these situations is natural, especially if you feel that anger is being directed at you unfairly, but it tends to just get in the way of finding a solution.

john-tells-all 7y ago
Absolutely. It's incredibly easy to be a condescending engineer, thus sabotaging yourself and your ideas. Practicing empathy is a tremendous benefit to yourself and your team! Esther Nam clearly explained this: https://www.youtube.com/watch?v=IYWlfVqBQLc https://www.youtube.com/watch?v=IYWlfVqBQLc
- john4534243 7y ago
  In my opinion anyone who does not have verifiable proof for their technical competency is not worth the time listening to their talk. I am not saying they don't have valid points but its too much of an ask.

WalterBright 7y ago

Like, I totally agree. Frankly, you're so right. Know what I mean? People really write too many words, basically, to say something they could express quite readily in far fewer words. Man, sentences go on and on saying the same thing over and over. I'll be honest, this is wearying and tiresome to read. Can't people simplify and get to the point? Do people even bother to read what they write? Too be perfectly honest, this is tiresome and tedious.

austincheney 7y ago
It's not just the written word. The same applies to the spoken word as well. When people in the military ask me how to improve their spoken word I tell them to focus only on rhythm and otherwise regard their content as sewage. Once the word is flushed from your mouth you cannot have it back. If the sewage (speech) stops flowing unintentionally the system backs up and cognitive problems take over, so keep pushing words out at a regular pace. That regular pace will eliminate the need for gap words like: uh, um, and ah. The content of the sewage is generally less important than the audience's reaction, so always be ready to pivot without causing a sewage backup.
- WalterBright 7y ago
  When people start a sentence with "I'll be honest with you" I'll often rudely interrupt saying "you mean you weren't honest before?" Yes, I know it is a meaningless filler phrase. I got tired of watching "American Chopper" partly because the son started every sentence with that phrase. A colleague basically of mine basically interjected "basically" between basically every couple basically of words, basically. So I basically started basically writing basically a lot of "basically" interjections basically in my basically emails basically to basically him. Fortunately, he basically had basically a great basically sense of basically humor. Like, totally.
  - austincheney 7y ago
    My favorite phrase to use in these situations is to use this as a compliment: It could be worse. It seems contrary to agree with as though the topic is horrible, but disagreement means the topic is the worst. It forces a moment of self reflection and then people suddenly become aware of the words spoken.

invisiblerobot 7y ago

Well written. Two excellent books are The Elements of Style and On Writing Well.