3 ms·

Good writing matters. One of the most undervalued skills in engineering, especially at the Senior+ levels. Being able to write a clear, concise, well-argued des

Good writing matters. One of the most undervalued skills in engineering, especially at the Senior+ levels. Being able to write a clear, concise, well-argued design doc will be useful to you long after the hot framework of the moment has become obsolete. And yet, few people take the time to hone the skill. Strunk and White is a classic, sure, which this article helps to put in context. But it’s 75 years old, and it has its problems (as the article discusses). I wouldn’t really recommend it anymore. Instead, have a look at: Williams and Bizup, Style: Lessons in Clarity and Grace And, for everything you ever wanted to know about standard American English usage (and how it’s shifting over time!), there is Garner’s Modern English Usage, which sounds dry but is actually fascinating (and inspired this brilliantly controversial review by David Foster Wallace: http://harpers.org/wp-content/uploads/HarpersMagazine-2001-04-0070913.pdf http://harpers.org/wp-content/uploads/HarpersMagazine-2001-0...).

Alex3917 6y ago
> And yet, few people take the time to hone the skill. Probably because it is, as you said, quite literally undervalued. Coding is just a writing job, so if you don't think that someone would get hired as a staff writer for The New Yorker then I don't see why you'd hire them to write in your codebase. But most companies don't think like that, much less put any actual weight on writing skills during the hiring process.
- fennecfoxen 6y ago
  Occasionally it is appropriately valued. A good tech writer, one who reaches out to engineers and figures out the hard stuff and plans an information architecture and documents your hardware product or your service's external APIs and tells people exactly how they work in a clear and systematic manner, can do fairly well at a company that needs this. (But they're hard to find, and many shops are just YOLO about that sort of thing.)
hcrisp 6y ago
If you like that kind of thing, also check out "Revising Business Prose" by Lanham. Avoid passive-voice sentences with long prepositional phrases, and instead use action verbs. For example: “The history of the new regulatory provisions is that there is generally an immediate resistance to them.” becomes “People usually resist new regulations.”
sokoloff 6y ago
My ability to write English has almost surely had more influence on my career after age 35 than my ability to write code. I wish I could go back and apologize to my English teachers along the way for how little effort and respect I offered to them/their courses.
- libraryofbabel 6y ago
  Conversely, I had no idea skills picked up when going to grad school in the humanities would prove so useful in getting promoted to and performing in the upper levels of the IC career track. (That said, I too was bored in high school English.) It is distressing how much emphasis is placed on mastering toy Leetcode-style algorithm problems in software career-building (for obvious reasons - they're used in interviews) and how comparatively little we emphasize the skills like writing and public speaking that actually count for some of the most successful tech folks.
  - ghaff 6y ago
    I have engineering degrees and was a product manger for a long time. My jobs over the last 20 years have almost nothing to do with anything specific I learned in an unrelated field of engineering--though learning to think/problem solving/etc. may well be. And far more to the fact that I've written for newspapers and have increasingly spoken and written on tech matters over the years.
clockwork-dev 6y ago
Nothing has impacted my writing more than that book. There are several versions now, the one I have is titled "Style: The Basics of Clarity and Grace". I chose it over White's book because of this passage from Clear and Simple as the Truth: > The best-known teachers of practical style are Strunk and White, in their ubiquitous Elements of Style. The best teachers of practical style are Joseph Williams and Gregory Colomb, in Williams’s Style: Toward Clarity and Grace and a series of academic articles and technical reports. Williams and Colomb present an incomparably deeper and more orderly treatment of practical style. The style they present is consistent and mature; it makes decisions about all the major questions that define a style, and is fully developed. I almost can’t overstate how much it’s changed how I read and write. Before that book, some writing just felt “clear” and other writing didn’t, but I couldn’t explain why. Now it’s much easier to see how that sense of clarity is created. Even though I don't write for a living and mainly do technical write ups, it was easily worth the time investment. This video is also good. It has a ton of interesting points, but the part about creating instability in your writing I found particularly useful. https://www.youtube.com/watch?v=vtIzMaLkCaM&ab_channel=UChicagoSocialSciences https://www.youtube.com/watch?v=vtIzMaLkCaM&ab_channel=UChic...
hazz99 6y ago
I really enjoyed “Classical Rhetoric for the Modern Student” also. A very in depth look, it’s a well-written textbook intended for later-year literature courses.
gfody 6y ago
Writing Effective Use Cases by Alistair Cockburn [1] is a pretty solid style guide for technical writing. [1] https://www.amazon.com/Writing-Effective-Cases-Alistair-Cockburn/dp/0201702258 https://www.amazon.com/Writing-Effective-Cases-Alistair-Cock...
rimliu 6y ago
https://signalvnoise.com/archives2/hiring_tip.php https://signalvnoise.com/archives2/hiring_tip.php

Alex3917 6y ago

> And yet, few people take the time to hone the skill. Probably because it is, as you said, quite literally undervalued. Coding is just a writing job, so if you don't think that someone would get hired as a staff writer for The New Yorker then I don't see why you'd hire them to write in your codebase. But most companies don't think like that, much less put any actual weight on writing skills during the hiring process.

fennecfoxen 6y ago
Occasionally it is appropriately valued. A good tech writer, one who reaches out to engineers and figures out the hard stuff and plans an information architecture and documents your hardware product or your service's external APIs and tells people exactly how they work in a clear and systematic manner, can do fairly well at a company that needs this. (But they're hard to find, and many shops are just YOLO about that sort of thing.)

hcrisp 6y ago

If you like that kind of thing, also check out "Revising Business Prose" by Lanham. Avoid passive-voice sentences with long prepositional phrases, and instead use action verbs. For example: “The history of the new regulatory provisions is that there is generally an immediate resistance to them.” becomes “People usually resist new regulations.”

sokoloff 6y ago

My ability to write English has almost surely had more influence on my career after age 35 than my ability to write code. I wish I could go back and apologize to my English teachers along the way for how little effort and respect I offered to them/their courses.

libraryofbabel 6y ago
Conversely, I had no idea skills picked up when going to grad school in the humanities would prove so useful in getting promoted to and performing in the upper levels of the IC career track. (That said, I too was bored in high school English.) It is distressing how much emphasis is placed on mastering toy Leetcode-style algorithm problems in software career-building (for obvious reasons - they're used in interviews) and how comparatively little we emphasize the skills like writing and public speaking that actually count for some of the most successful tech folks.
- ghaff 6y ago
  I have engineering degrees and was a product manger for a long time. My jobs over the last 20 years have almost nothing to do with anything specific I learned in an unrelated field of engineering--though learning to think/problem solving/etc. may well be. And far more to the fact that I've written for newspapers and have increasingly spoken and written on tech matters over the years.

clockwork-dev 6y ago

Nothing has impacted my writing more than that book. There are several versions now, the one I have is titled "Style: The Basics of Clarity and Grace". I chose it over White's book because of this passage from Clear and Simple as the Truth: > The best-known teachers of practical style are Strunk and White, in their ubiquitous Elements of Style. The best teachers of practical style are Joseph Williams and Gregory Colomb, in Williams’s Style: Toward Clarity and Grace and a series of academic articles and technical reports. Williams and Colomb present an incomparably deeper and more orderly treatment of practical style. The style they present is consistent and mature; it makes decisions about all the major questions that define a style, and is fully developed. I almost can’t overstate how much it’s changed how I read and write. Before that book, some writing just felt “clear” and other writing didn’t, but I couldn’t explain why. Now it’s much easier to see how that sense of clarity is created. Even though I don't write for a living and mainly do technical write ups, it was easily worth the time investment. This video is also good. It has a ton of interesting points, but the part about creating instability in your writing I found particularly useful. https://www.youtube.com/watch?v=vtIzMaLkCaM&ab_channel=UChicagoSocialSciences https://www.youtube.com/watch?v=vtIzMaLkCaM&ab_channel=UChic...

hazz99 6y ago

I really enjoyed “Classical Rhetoric for the Modern Student” also. A very in depth look, it’s a well-written textbook intended for later-year literature courses.

gfody 6y ago

Writing Effective Use Cases by Alistair Cockburn [1] is a pretty solid style guide for technical writing. [1] https://www.amazon.com/Writing-Effective-Cases-Alistair-Cockburn/dp/0201702258 https://www.amazon.com/Writing-Effective-Cases-Alistair-Cock...

rimliu 6y ago

https://signalvnoise.com/archives2/hiring_tip.php https://signalvnoise.com/archives2/hiring_tip.php