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-0...).
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.
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.”
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.
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.
> 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.
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.)
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.
My mind was slightly blown when I realized "Charlotte's Web" was halfway written (I guess he revised it and added a chapter) by the same guy as "The Elements of Style." There are incredibly few authors that you read multiple books from in a K-12 education, and I'd never put that one together because a style guide is so different from a children's book.
Charlotte's Web is also a literary masterpiece - definitely reread as an adult if you only remember it from your childhood. The Audible is narrated by EBW himself.
I just started re-reading Charlotte's Web after reading this comment a few hours ago, and wow. What a charming and elegant book!
I had no idea the book was so funny:
Wilbur paused and listened. All the other animals lifted their heads and stared at him. Wilbur blushed. But he was determined to get in touch with his unknown friend.
“Attention, please!” he said. “I will repeat the message. Will the party who addressed me at bedtime last night kindly speak up. Please tell me where you are, if you are my friend!”
Whenever I find a copy of Elements of Style, I throw it away. I have deep-sixed at least four copies in the past five years.
Geoff Pullum, at Edinburgh, calls it "The Nasty Book", because it makes people needlessly insecure about their writing, and because its supposed rules are not followed by any great writer.
The most damning fact is that, when he produced the second edition after Strunk died, White made up a bunch more phony rules, and then went through Strunk's original text and doctored it to obey them. Then, he failed to obey them in his own text--frequently on the same page where he was advocating them.
There is a certain amount of correct advice, but it is the same as elsewhere, e.g.: "omit needless words". Did we need a book to tell us that?
I disagree with what you're doing and disapprove of it on principle that destroying a book which may have some useful knowledge in it is to be avoided.
I recommend you cease this activity for karmic reasons.
When the net effect is harmful, destroying the book preserves what would have been damaged. The uncritical popularity of the book demonstrates that its readers cannot distinguish the useful knowledge from the poisonous trash.
You might equally argue that spoiled food still contains potentially usable calories, so should not be discarded.
It seems clear that White (though Strunk seems to have been rather more serious about it) intended his usage guidance to be just that - guidance. Certainly I've found it useful to know the rules well in order to understand when and why they should be bent or broken.
Certainly I've found it useful to know the rules well in order to understand when and why they should be bent or broken.
I think this is a key point. In my favorite writing course in college, the professor chose to teach composition from the perspective of legal argumentation. We wrote 4-8 pages per week in the most economical and intentional way possible, poring over every word, every sentence, and every paragraph to make the language easy to understand and to make every word do work.
The professor never pretended that this was the best way to write and never claimed the result would be beautiful, though he did claim that the result would be easy to understand, which it was. Peer editing in that class was the smoothest experience I've ever had in a writing class. But he accomplished something that no other writing instructor did for me before this class: he taught how to make grammar, diction, rhythm, and even connotation an intentional thought process. He also taught how to think clearly about the point you wanted to get across.
That wasn't going to teach any of us beautiful prose or how to craft good plots, but it got us very quickly to the point where our writing style became deliberate.
> That wasn't going to teach any of us beautiful prose or how to craft good plots, but it got us very quickly to the point where our writing style became deliberate.
I would argue precisely the opposite.
You can't build beautiful woodworking until you can do a joint reliably and repeatedly. You can't play jazz on your musical instrument until you can play scales reliably and repeatedly.
You had a really excellent writing professor. He completely anchored the fundamentals that you needed. Now you can actually proceed to actually write.
You had a really excellent writing professor. He completely anchored the fundamentals that you needed. Now you can actually proceed to actually write.
Not going to speak for my own writing, but I completely agree with your point. The better you understand the fundamentals of composition, the better you understand what makes good writing good, how to hone your own style, and how to tailor your writing to the situation.
I think of The Elements of Style as one of those attempts to break writing (in English) down into its mechanical elements. Whether or not I agree with its advice, I respect the approach it tries to take.
I've found following Strunk's "make every word count" dictum causes me to take much more time when composing. So 4-8 pages per week sounds like it would take an awful lot of time indeed
This was especially true when everything was written out by hand. Editing on a computer changes the time to rewrite something by at least a factor of 10, maybe 100.
It's something I aspire to[0] and as elsewhere pointed out, it takes extra time. As your expected audience grows, the value of your time invested grows because it benefits proportionately more people.
I've learned to explain in terms almost stupidly simple because another's interpretation can be so extraordinarily far from your intent you wonder how they even got there. Then they explain how it reads to them, and inside you groan a little because yes, it could be seen to mean that and you had no idea. One needs to user test one's writings just as much as one's software, I've discovered.
It absolutely did, but it was focused practice, so it gave you back what you put into it. I got better over time, so by the end of the class I was much faster at the process of putting the words down and then making multiple passes to clean it up.
See also Cormac McCarthy’s tips on how to write a great science paper:
When you think you’re done, read your work aloud to yourself or a friend. Find a good editor you can trust and who will spend real time and thought on your work. Try to make life as easy as possible for your editing friends. Number pages and double space.
Can you elaborate, for the non-linguists? His prescription seems sensible:
i. Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
ii. Never use a long word where a short one will do.
iii. If it is possible to cut a word out, always cut it out.
iv. Never use the passive where you can use the active.
v. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
vi. Break any of these rules sooner than say anything outright barbarous.
... but I'm well aware of how sensible an asinine prescription can seem to a layperson.
For example, "the passive" is rarely defined in a coherent way, or matches the actual definition of "passive voice". Worse, though, is that it is very bad advice. What are called passive senses are tools to correctly place emphasis which, done well, aids clarity.
Often a long word captures a nuance the short version can't. Its presence, by itself, calls the careful reader's attention to the distinction between it and the shorter word it displaced, without belaboring it.
Metaphors, similes, and figures of speech are the furniture of language. Most words, standing alone, embody one. Orwell certainly did not obey this stricture, or he would have been mute.
A word that could have been cut, but wasn't, calls attention to the choice made not to cut it, inviting curiosity why it wasn't, which you may then answer.
Foreign, technical, and jargon words tell the reader about your context. Substituting a word unfamiliar in that context generates confusion, and questions about what distinction you are trying to make by avoiding the usual word. Sometimes you are, in fact, making such a distinction.
Careful readers learn to recognize when writers are making their choices judiciously, and draw extra meaning from them.
So, better advice would tell you to put each such choice to work on the hard job of communicating.
Then learn that they were never rules at all, and were invented from whole cloth just to make him seem smarter and you dumber. No good writer follows those rules, chooses to break them, or even so much as thinks about them.
I don’t see any reference to “white supremacy” in that link.
> Instead of requiring that comments be written in Strunk & White Standard English, require instead that English-language comments be clear and easily understandable by other English speakers. This accomplishes the same goal without alienating or putting up barriers for people (especially people of color) whose native dialect of English is not Standard English.
I think we can all get behind this. The idea is that if you speak Indian English and refer to the contents of a written program as “codes” rather than “code”, that is completely fine, since it is clear and easily understandable by other English speakers. Strunk & White is kind of a trainwreck of a style manual anyway (the linked article articulates many of my complaints, but I have others). Maybe its popularity was deserved in earlier decades, I don’t know, I’m not a historian.
I think it’s fine and good that people hash these things out in the mailing list. I see no point in digging through mailing lists and making attributions to “Python Developers” as a whole, based on something at the very least they decided they wanted to remove from commit messages.
Indeed they are, as is much of the Western canon. They are the products of a period and locale in which white supremacy was more or less unquestioned by a large proportion of the English-speaking population.
"The Elements of Style" is still useful and interesting, but its limitations and origins must be acknowledged. Among them is that it is a collection of usage patterns chiefly used by and intended for a specific class of English speakers. That class was not inclusive or representative of all the ways English is written or spoken, nor necessarily even of the "best." The book should be one source among many for those who hope to communicate clearly and concisely.
> They are the products of a period and locale in which white supremacy was more or less unquestioned by a large proportion of the English-speaking population.
By that standard, James Baldwin's writing is a relic of white supremacy and homophobia because he wrote when both were more or less unquestioned.
Or, by a more sensible standard, you have carelessly besmirched a writer's reputation by associating him with white supremacy via a vague claim about historical attitudes and no reference to his beliefs or the content of his work.
As a strategy, I suppose it has the benefit of not requiring much thought or evidence.
James Baldwin's writing certainly is "the product of a period and locale in which white supremacy was more or less unquestioned by a large proportion of the English-speaking population." Do you think it is otherwise? I am not dismissing the work, I am looking at its context.
White supremacy is more than klan rallies in Alabama. It was a major part of thinking and writing in the US and English-speaking world in general for a long time, a mindset and set of assumptions and lessons that changed how everyone did pretty much everything. It's hard to imagine any major piece media emerging from the 19th-20th centuries that does not bear the mark of white supremacy in one form or another.
>It's hard to imagine any major piece media emerging from the 19th-20th centuries that does not bear the mark of white supremacy in one form or another.
This is true, but it also entails that it's easy to selectively weaponize opposition to white supremacy against virtually any target. Is there something you don't like? Chances are that it has a real historical connection to white supremacy, at one or two degrees of removal.
You're quite right, I should have written something along the lines of "conventionally important works in English" or the like. Of course the western canon is much more diverse.
> Strunk’s likes and dislikes, explains White, “were almost as whimsical as the choice of a necktie,” yet he had an uncanny ability to make his preferences “seem convincing.”
This is an important point: Learners need to have preferences fed to them, as they have none of their own, but the next step in learning is making your own preferences, not blindly following the ones given to you.
Also, a point of humor I rarely find anyone mention:
> “Omit needless words!”
Ha! And triple ha! How superfluous that is. Why does it need to specify "needless" at all? Are we going to omit essentials? Of course not! And it explicitly says "words" right there. Right there, mind you! What else are we to omit, lemons? Obviously, the dictum must be "Omit!" and it must never be repeated. Superfluity, in this case, does vitiate.
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-0...).