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.
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.)
1. business
2. entrepreneur
3. your, you're
4. its, it's
5. they're, their, there
Also, for the term paper due at the end of the semester, for every day the paper was late, one grade would be subtracted. I.e. 2 days late meant a B would become a D. No excuses would be accepted, as they had the entire term to get it done.
The first time he taught this course, half the students were a day or more late. He followed through. The next year, word apparently got out as he only received one late paper.
His point was that in business, excuses were not acceptable.
It's important to teach the values of timeliness and attention to detail, but you aren't teaching anything if you're not giving students a way to recover and improve.
If you're in business, and write business letters misspelling "business", you aren't going to be taken seriously (though you likely won't realize why the rejections are happening). If you graduate from a business school and can't spell "business" then the school's reputation suffers, too.
In college, you're an adult. The requirement that "business" be spelled correctly is made quite clear. No excuses, no bullshit.
So one day, he got the pilots together, went out to the runway, painted two strips crossways and demanded that all pilots touch down within the stripes. There was a bunch of whining about it from the pilots that it was unfair and impossible.
So Yeager fired up a jet, took off, circled the field, and landed precisely in the center between the lines. He got no more guff from the pilots and they straightened up.
Me, if I was in a combat squadron I'd choose to serve under Yeager rather than a commander that tolerated sloppy flying skills. Sloppy skills will get you killed in aviation and especially combat.
Story is taken from "The Fog of War" as told by Robert S. McNamara.
Caltech had a famous class, EE91 lab. The rules were simple. The first week, you produced a spec for a project. If the spec was approved, you had the whole semester to get it done. If the project met the spec, you got an A. If you didn't, you got an F. Again, no excuses, no bullshit. It was a very popular class.
I took it too, was very careful to spec something I could accomplish and got it done well in advance.
These students aren't in kindergarten. They're adults in college. And getting your project designed, built, and debugged is a LOT harder than remembering how to spell "business".
The disservice to the students was done by all their prior teachers who'd make such conditions and never enforce them, and they didn't believe my dad would, either. What was he supposed to say, this time I really really mean it? (He did say that.)
I've heard innumerable such conditions from teachers, none of them ever followed through except EE91 lab.
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.
In my experience, this isn't true. When revising, most of my time is spent considering what changes I can make and not putting them into practice. If the bottleneck is thinking, raising your typing speed will provide marginal gains at best.
(Not claiming that that's actually faster, or otherwise.)
Rewrite from scratch as necessary. :-)
* 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."
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.
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.
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.
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.
I will confess that what I say is usually entirely determined by what I have to say, without checking for my audience's reaction.
Writing can not be compared with speaking. Writing has the advantage of thinking over multiple times and editing before sending out the final draft.
“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.
"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?
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.
This is the fundamental problem.
S&W is very good at taking people who "can't write" and teaching them 1) writing is a skill, 2) you can improve by practice, and 3) the basic practice is not very hard. I don't think it's a coincidence that the book remains popular among engineers who (often justifiably, based on some bad teacher) have been turned off to writing.
But also because writing is a skill, the achievable level is very high. (Much higher than I will achieve. I have a family member who is a professional author and dabbles in software development; I see where they are in software development, and realize I'm at the same place in writing). And there are different types of writing, for different goals, towards different audiences. Persuasive writing is not the same as technical documentation is not the same as poetry!
All of this matters but S&W pretend it doesn't.
A former CTO of mine told me of their previous position (where their reportees were writing primarily Java; we were writing a different language): The value of Java is that it establishes a floor. Anyone hired could be guaranteed not to fuck things up and contribute at least X additional value or work on features of at least Y complexity, and in that market / at that scale that was more important than providing an environment that made it easy for the experts to excel (which they could still do, just with more effort).
The book offers specific rules to follow, and if you follow them you will achieve at least mediocre writing. It's the Java of informative writing. If you are awful at writing and internalize those lessons you will improve and it will probably be some kind of professional boon. But there is so much more to writing, and you do yourself such a great personal disservice if you don't at least glimpse it.
(On the other hand, at the time I told that CTO I couldn't imagine working at such a place, and they agreed it wasn't appropriate for the current workplace. Now I'm touching management level in another company where I wish more of our programmers had a "mediocre language" floor rather than the more free-wheeling approach the company has. It seems there are very few places where the rewards of expertise beat the averages. But on the other hand, I still fucking hate writing Java.)
As for the analogy: without the "drawing" part, it might at least be accurate - but a lot of its force rests on that lie. Persuading people with lies is easy, but, well, wrong.
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.
good writing != concise writing
My friend gave me great advice: he asked "hey can you unpack that for me?" -- my text was too concise and not clear.
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.
Esther Nam clearly explained this: https://www.youtube.com/watch?v=IYWlfVqBQLc
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.
I haven't met a single senior dev in person that could write good.
- Harold Abelson
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 :)
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.
Two excellent books are The Elements of Style and On Writing Well.
* 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.