There’s an idea in your head.
You produce some text with your fingers.
I consume that text with my eyeballs.
Some idea forms in my head.
Phrased like this, your aim is obviously that the idea in my head closely resembles the idea in your head. Don’t get distracted by trying to make your text more closely resemble the idea in your head; your text is just a tool to get past my eyeballs and into my brain.
The best advice I have for improving that resemblance is this: Re-read your writing looking for other possible ideas that could be formed, and then edit it such that it is incompatible with as many of the other ideas as possible. You may need to put it down and come back later with fresh eyes in order to see those other possible ideas.
This sounds like the cliche advice of “re-read and edit, put it down and come back with fresh eyes“ - because it IS that cliche, expanded into the most specific and effective form of itself that I know. Unfortunately, the cliche by itself isn’t as helpful, since there are many other ways to expand it. You could re-read, but looking to see how closely it resembles the idea in your head (a common mistake, I cautioned against it above). You could edit, but such that it has fewer words (aesthetically pleasing for sure, but it risks sacrificing that all-important ‘inter-brain idea-resemblance’). You could come back with fresh eyes thinking the goal is to rediscover and refine the idea that’s already in your head (a good way to think, but this is more precisely called ‘journaling’ and it doesn’t have much to do with writing to communicate.)
Case in point: it was only upon re-reading my comment and thinking ‘damn, that last paragraph is really long, can I fix that?’ that I realized the entire last paragraph is literally me being worried that you’ll see “re-read … edit … come back with fresh eyes” and then the idea that ends up in your head will just be whatever you usually interpret the cliche to mean, instead of the very specific process I have in mind! I should also add a concrete example, those are usually very effective. I suspect concrete examples are helpful precisely because they are derived from your idea and not from your text description of the idea: there’s a cloud of possible ideas compatible with the text you wrote, and there’s another cloud of possible ideas compatible with the examples you give, and the intersection of those two is quite specific.
I absolutely agree with this, and will add that one thing I do is have other people read it and see what they think and if there is any confusion at all I don't ever chalk it up to the reader or just try to get them to understand: I try to edit my article to prevent that mistake from ever having been conceived of; too many people are just like "engh: that's just one opinion and a bunch of other people got it" without realizing how their test readership likely has a sampling bias or that 1/10 is actually really bad.
I will forewarn against following this advice blindly however, because it heavily relies on your audience. Any mature writer should on some level conceive of a precise population of consumers for their work and write to that population, and indeed say “eugh that’s an irrelevant opinion” to people outside of their audience. This is also referred to as having authorial intent or voice. Writing a technical analysis of a very strange bug doesn’t necessarily need to highlight that this isn’t entomology!
Relatedly, soon after I wrote that comment, I thought "I wonder if someone is going to think I meant random people whom weren't even in my audience, as opposed to only people I wanted to read my article in the first place", but then I was driving and it was just a comment and I was like "engh"... the next day, I come back to your comment feeling a need to correct me, and so I should have probably pulled over because these feelings really aren't something to ignore.
I do this too and it’s very helpful. Just be aware that anything the reader tells you is necessarily going though another round of brain->text->eyeballs->brain. Read their response carefully, lest your brain smudge their words enough to simply pattern-match it back to your original idea.
That's extremely true, but for writing non-fiction.
For writing fiction, it's perfectly possible to have a tradeoff writing to be evocative vs being clear and precise. Tolkien and Fleming spring to mind.
Agreed, a fiction writer trying too hard to put a specific idea in my head all the time is going to annoy me. Not all fiction all the time, though - Sanderson’s novels appeal to me in part because he is very specific about how his magic system works, while being more free about other elements. And not all non-fiction all the time, either - I love a good evocative phrase alongside all the specifics, it gives me a feeling to go along with the understanding. The aim of fiction, then, is not to achieve perfect idea-resemblance, but rather to produce the most beautiful or engaging ideas in the reader’s brain that one can, without caring too much how closely that idea resembles the author’s own.
Man, evocative is a really good word. Perhaps we can talk about “communicative writing” “evocative writing” instead of non-fiction and fiction respectively, so we’re not bogged down with genre categories or factual accuracy.
I used to mentally stick on writers like Tolkien, Fleming, Frank Herbert, Philip K Dick, because I had to reread their more dense passages multiple times, and even then it was still unclear to me what specifically they were describing, but eventually I figured their intent was more to evoke whatever associations each individual reader made, than to clearly communicate the same thing. So then I decided that some fiction should be read differently, more casually and without an obsession with clarity, unlike non-fiction or technical stuff.
Actually, it's William Gibson's cyberpunk writing which turns up the dial on evocative-over-coherent to 11. It's a kaleidoscope of words seeking subjective associations in each reader's mind.
There was one completely impenetrable section (Mona Lisa Overdrive, maybe?) the paragraph that contains "the armature of his pleasure" or something.
At my programming job I find that when I communicate, my sentences are too long and have too much detail to the point where people probably skim over what I write and don't really read it. Looking at other coworkers who seem to be effective communicators, they seem to be more economical with their words with the use of jargon (in a good way) that encapsulates more complex ideas into a word or term. For example, I would write "when the thing we use is shared by many other things" and the shorter term would be "multi-tenant". When "one of the things uses too many resources and disrupts the other things in the shared environment" the shorter term is "noisy neighbors problem". So I find that finding the right word or jargon is really helpful for making writing easy to read.
I do this often, namely asking myself "is there any way this could be misread or come across as ambiguous?"
Unfortunately that also trains my brain to look for ambiguity in text, which leaves me frustrated when I don't see the same amount of specificity around me.
The most useful lesson about writing I learned I did actually learn in school (in a mandatory writing-intensive course in college): to re-read and edit.
I think it was specifically that reading what you wrote aloud (or mouthing it silently) is a way to get a fresh look at what you wrote. It helps you realize both 1) more natural sounding and 2) more logical ordering of words than the stream of thought you wrote down.
My initial stream of thought when writing is always a garbled mess. So this technique made a big difference for me.
The most that my favorite books on writing (mentioned in the article as well: Zinsser's On Writing Well) helped with was just cutting out unnecessary crap.
Not to say it doesn't help to read these sorts of books. And I agree with the author that just writing (and continuing to write as practice) is best.
Borges also followed this point of view. He was allegedly so fussy about rewriting and fixing his writings, he sometimes thought of corrections for second editions, if it was too late because the text was already in print.
I always suggest Developing Quality Technical Information, and I'll link to both Amazon [0] and my personal review of it [1]. This is the best book about writing I've ever read, and it's significantly improved my writing in concrete ways. One small example is that I no longer put gerunds (verbs ending in -ing as a noun) in any title or heading, because these don't translate well into other languages in such a context and as such may cause a non-native English speaker to slow down in their reading (or mess up your translator's job if they need to do i18n). But there are much more far-reaching changes; I tend to be a lot more concise, delete adverbs, force myself to use parallel structure, etc. As this blog post's author might put it, I'm a lot more judicious about when and where to employ my voice.
> We were never told to use fewer, simpler words. Clarity was never a criteria.
I agree. I'd even go as far as to say we're taught the exact opposite: You will get penalized in some courses for using simple words or not meeting arbitrary word-counts.
What I always found particularly contradictory is that you are taught in High School you needed to write an advanced way "for college," but when you get to college the standards were lower. Then you get told you need to write verbosely because "for work," but then you get into work, and it is middle-school writing styles and complexity ruling the day.
It is exactly the same thing with cursive. Nobody wants cursive in a professional setting, ever.
Curious, haven’t really thought about this before.
Seems like your observation is a strong sign that schooling and academia are run by people who’ve only worked in schooling and academia, which isn’t news obviously, but made more salient by an issue such as yours.
A lot of it is just that clarity is much, much harder to measure than word count or even vocabulary usage. The system almost can't avoid incentivizing what can be measured, and is almost incapable of incentivizing clarity (consider the task of grading 40 papers over the course of a few days and see if you still think it's reasonable to expect otherwise. And honestly, it's true that students need to prove their ability to write long pieces, and it's, again, hard to measure whether the student is covering enough ground to cover the length you want to see. You get what you measure, and what you can't measure is very hard to get (absent relatively intensive personal attention, hard to scale). I don't know a solution.
My only addition is that in my educational experience, a number of times someone would came in to teach with an entirely practical and non-academic background, and it was always a clear and tangible breath of fresh air. Their approach, priorities, clarifications, honesty and insights always had a comparative sense of vitality and importance about them, irrespective of how good a teacher they were in the normal sense.
Your point still holds about how to assess, which as you point out, is its own thing. But it also doesn't exclude the possibility of recognising and providing the value of education from those outside of the education/academic system, however hard that value may be to measure.
You can feel the effects of this when people have to write fancy for a cover letter or an important email. People switch to a different voice that isn't theirs, and that they are clearly not comfortable with.
I thought at one point that Paul Graham and David Perell were “good” writers, then I started reading and writing voraciously. Now that I’ve read many great writers in all sorts of topics such as philosophy, business, finance, self-help, history, and many more, I cannot really appreciate these internet writers as much as I used to. In fact, I can’t really read them much without feeling they are too pretentious. But I do appreciate them helping me grow to appreciate the art form.
Maybe the author will also go down a similar path and read great books from great authors.
“If you want to be a writer, you must do two things above all others: read a lot and write a lot. There's no way around these two things that I'm aware of, no shortcut.”
Everyone likes to give writing tips. What I have learned for for something as difficult as writing and as unpredictable as how people consume it and respond to it, is that there are no obvious rules beyond the basics like grammar and spelling.
What makes some writing successful and other writing not, is sometimes a coin toss. Or so many variables, who knows. Some people say to write simply or minimalistic, but others have had huge success with a more complicated writing style.
Writing is 80% preparation, 20% writing
Preparation is part of the writing process though. That is what editing is for.
When I’ve talked to professional writers, they say the best way to become a good writer is reading the work of writers you admire. And not just reading their work but analysing and dissecting it. Find sentences and paragraphs you admire and study them. Pull them apart to see how they work. Try to understand the syntax and the rhythm and the rhetoric underlying them. Write variations until you remember them. Eventually you’ll have a mental catalogue you can call on while you’re writing.
Interestingly, this is pretty much how you learn to write music. Don't writing schools teach this method also? Or any creative pursuit? But then, the article ends with:
I'll spend 30 minutes writing a short email, or many hours... just because I re-read it so many times. I re-read it every single time I've looked at anything else for even a second, because I'll feel like I need to refresh the entire context to add the next paragraph. I'll re-read the entire thing periodically as I write it, to make sure it flows alright. Every time time I read it, I fix every error I can find as I go... and then re-read it again with the corrections. I repeat until either I find no errors, or I don't feel like caring any more.
I've done this with essays spanning thousands of words. I'll re-read the entire thing every 5 minutes or so. I'm so paranoid about it.
And then I'll find out anyway later that I should've listened to some tiny doubt that I dismissed.
Good writing requires refining and editing as much as developing an outline and a first draft. Reading the piece aloud will trigger a natural editing and refinement process and is useful for important content.
I find Grammarly helpful for spotting problems in writing, I agree with about half of the suggestions but the review is still helpful. I have paid copy editors for books and important articles I have written.
Start with the audience you are writing for and what you hope they will learn or the actions you will encourage / enable.
Getting a first draft via dictation can be a better way to start than typing. Try it once or twice.
For important pieces ask for feedback from folks who are a good proxy for your target audience or are familiar with their needs.
Writing well is difficult for many, and I believe one of the reasons is because people don't read much anymore. Whether it's fiction, non-fiction, or poetry doesn't matter, as long as you read. But our attention spans have become so short that we need small, quick dopamine hits.
I used to read voraciously; the longer books the better. Every Stephen King book, Neal Stephenson series, I just loved to lose myself in a good book to the exclusion of everything else.
Now I find I have to focus before I can truly lose myself in a good book.
I'm a firm believer that you can learn to write by following style guides, quotes from Hemingway and King about 'killing your babies' etc. But to become a great writer you have to be a reader.
I'm not sure that fits. I find writing extremely easy, and most of my colleagues and friends hate writing and are poor writers. All of the good writers/authors I know find writing easy. It's still work, but it's not ditch-digging hard.
To be a great writer you must indeed become a voracious reader. Stephen King says as much in On Writing, I believe (I assume you've read On Writing; if not, I really recommend it).
Strangely I don't think public schools do a good job teaching children how to write. I chalk this up to the fact that most school are testing and metrics driven and writing is somewhat more subjective.
I agree with most of the points but I will say (as someone who writes for a living) that it is "easy" once you've learned how to do it. Writing is hard as hell if you don't know the rules past high-school level requirements.
Case-in-point: several of my non-work friends are ESL and some of them are taking technical writing courses. I've seen their assignments and have given them copyediting help. They're shocked that I can carve out the assignment in five minutes. Usually their problem is the first rule from Strunk and White: use less words.
I consider myself pretty decent at writing. I don't love writing but it has always come fairly naturally to me, much easier than it appears to come to most people. Which is surprising, given how absolutely mediocre I am at nearly everything else in life. :) ("Those that can, do. Those that can't... write?")
I'm frequently aghast at how utterly _terrible_ most technical documentation is. Even the docs for a lot of prominent enterprise and open source software is just awful to use. What drives me the most insane is dry, passive voice. Passages that descriptive rather than prescriptive ("the widget is a surmounted on a logarithmic casing, widdershins of the two spurving gears"), contain zero diagrams or illustrations of how things are put together, and _definitely_ don't contain anything like a tutorial or getting-started guide.
Every once in a while I consider jumping into the field of technical writing just to clean it up a little. But I would probably find it immensely dull after a short period of time.
I have explored technical writing a little bit. There are actually a fair amount of people that have majored in the humanities or literature of some sort. They complain about how they have to write in a dry, passive voice. If some of them had their way, the documentation would read differently.
I don't think anyone in tech writing is trying to put out bad documentation. I've read many complaints about not being given access to the device or software, being left out of license provisioning, being kept out of the loop in sprint planning and other meetings, or being told late in the documentation stage that functionality has changed. If the writers don't have access to blueprints or can't access the software, documentation doesn't get pictures. Some of the devs and engineers respond poorly to requests for screen grabs or doing other administrative work for the tech writers.
I don't think there is a simple solution here. What are the incentives and how does tech writing help or harm. In some cases, helping a tech writer is time spent away from development. Or you can blame UX issues on poor documentation to blame the tech writers.
Yeah. These days I mostly do a lot of writing and a lot of editing. And I suspect I can sometimes coast a little bit because people assume that what I do (for me) is a lot harder than it actually is. Though it's never really easy and does involve a lot of pacing to get through some writing "problem."
I don't think that's a good way to put it. Some people will hate writing and love to have written because they hated the act of writing.
For me, writing is laborious, challenging, but the process is fun. I look forward to writing. Am I the only one? I don't think so.
It's like lifting weights or training for a sport. Some people may hate the process, if they had the choice of, say, lifting weights or not lifting weights and getting the same exceptional results for their bodies, they'd sit on the couch gorging themselves on Doritos. I like lifting weights: breathing hard, the blood pumping, the strong feeling of being alive. Not just the results.
quite a lot of my career has been writing - reference material and training courses, and a few short stories. apart from the latter, all of which were crap, my advice would be:
- know what you are writing about. it is very hard to write on a subject you have little knowledgr of
- pick an example that you have seen and found helpful (i chose MS c++ help - the old stuff not the new crap) and model your text on that
- if possible, get it reviewed, if it is a course then teach it from what you have written - the punters will not be kind to a badly-written course
- use professional grade tools, if you are doing this for real money - i used framemaker for most of my technical writing
I was sad to see this article not mention Orwell’s Politics and the English Language. It is one of the best guides to writing clearly and concisely I’m aware of. Too much writing meanders and fails to say what it means.
Some of the best insights on writing have come for me from a book on reading, Mortimer Adler's classic (and HN perennial) How to Read a Book.
When you realise that written communication is a conversation, across not only space but time, that the author and reader are both participants, and that each benefits by consideration of the other, in preparing to receive or be received, and to assemble similar structures of understanding (the author the original, the reader a copy), and to both be questioned and challenged, and to question and challenge the narrative, the thought that the acts of reading and writing have much to learn from one another makes a great deal of sense.
Another recent insight is that whilst we have language centres in our brains, there is no reading centre. That is, reading is an entirely learned activity, and though based on evolved capabilities, there's not innate evolved structure supporting it (yet) within neurological anatomy. This from Maryanne Wolf on the Ezra Klein podcast last November:
This seems like really non-constructive advice. Are they even tips? Like "your voice is you not how you write" - what does that even mean from an ontological prespective?
Phrased like this, your aim is obviously that the idea in my head closely resembles the idea in your head. Don’t get distracted by trying to make your text more closely resemble the idea in your head; your text is just a tool to get past my eyeballs and into my brain.
The best advice I have for improving that resemblance is this: Re-read your writing looking for other possible ideas that could be formed, and then edit it such that it is incompatible with as many of the other ideas as possible. You may need to put it down and come back later with fresh eyes in order to see those other possible ideas.
This sounds like the cliche advice of “re-read and edit, put it down and come back with fresh eyes“ - because it IS that cliche, expanded into the most specific and effective form of itself that I know. Unfortunately, the cliche by itself isn’t as helpful, since there are many other ways to expand it. You could re-read, but looking to see how closely it resembles the idea in your head (a common mistake, I cautioned against it above). You could edit, but such that it has fewer words (aesthetically pleasing for sure, but it risks sacrificing that all-important ‘inter-brain idea-resemblance’). You could come back with fresh eyes thinking the goal is to rediscover and refine the idea that’s already in your head (a good way to think, but this is more precisely called ‘journaling’ and it doesn’t have much to do with writing to communicate.)
Case in point: it was only upon re-reading my comment and thinking ‘damn, that last paragraph is really long, can I fix that?’ that I realized the entire last paragraph is literally me being worried that you’ll see “re-read … edit … come back with fresh eyes” and then the idea that ends up in your head will just be whatever you usually interpret the cliche to mean, instead of the very specific process I have in mind! I should also add a concrete example, those are usually very effective. I suspect concrete examples are helpful precisely because they are derived from your idea and not from your text description of the idea: there’s a cloud of possible ideas compatible with the text you wrote, and there’s another cloud of possible ideas compatible with the examples you give, and the intersection of those two is quite specific.