I've read "On Writing Well". I then discovered "Style: The Basics of Clarity and Grace" by Joseph Williams. "Style" is better than "On Writing Well". "On Writing Well" opened my eyes to what bad writing is, while "Style" explained how to write clearly. He took an impossible topic - writing clearly, showing you the elements of clear, consistent and impactful writing, distilling down into actionable lessons. The advice is not vague like "Use the active voice", "Don't start sentences with And"; he shows you why with examples. Even the passive voice is more suitable in certain cases. After reading the book, it changed the way I read and write. Very few books change the way you think. "Style" is one of them.
I was so disappointed with this book. Some of the platitudes Zinsser goes into are reasonable, like try to be uncluttered, direct and to the point, but all the worked examples seem to just be arbitrarily chosen to his taste. For example, in the chapter on "clutter", Zinsser picks out this passage from Walden as his exemplar of "uncluttered English":
"I went to the woods because I wished to live deliberately, to front only the essential facts of life, and see if I could not learn what it had to teach, and not, when I came to die, discover that I had not lived."
Dense, incredibly difficult to parse, with a non-standard use of "front" as a verb and what seems to be a triple-negative. If I said that sentence to you, out loud, I doubt you would catch the meaning of it on the first pass. The book is filled with stuff like that.
That said, I really do want to get better at non-fiction writing, specifically technical writing, but I haven't found any good recommendations for "canonical" books on technical writing. If anyone can suggest a decent, pragmatic (as opposed to Strunk-and-White style prescriptivism) introduction to technical writing specifically, I'd appreciate it.
"I went to the woods because I wished to live deliberately, to front only the essential facts of life, and see if I could not learn what it had to teach, and not, when I came to die, discover that I had not lived."
Dense, incredibly difficult to parse, with a non-standard use of "front" as a verb and what seems to be a triple-negative. If I said that sentence to you, out loud, I doubt you would catch the meaning of it on the first pass. The book is filled with stuff like that.
I don't think that's difficult for educated native English speakers. Walden was written in 1854, and most people who went to high school in an English speaking country would have some exposure to Shakespeare which is 250 years older than that - so I really don't think it's very archaic. Are you a non-native speaker? You write English completely fluently but if you've had no real exposure to the literature I can understand why you might find it hard going.
I haven't taken English since high school, and had no "liberal education" at university, and I did just fine with the audiobook (ie the whole thing was read aloud to me). I am not going to pretend it's easy to understand as modern, informal speech but it certainly wasn't arduous.
I completely agree. As another native English speaker I find the highlighted passage parses incredibly naturally. It feels like a single cohesive thought without the need for back-referencing despite encompassing several 'ideas'.
It's slightly stylised 19th century English, which is very different to 21st century English. We don't use run-on sentences peppered by parenthetical clauses nearly as much as we used to, so I'm not surprised some readers may find it dense.
For more modern English, I think George Orwell is very hard to beat.
For blog posts, Paul Graham is always worth reading - not so much for the content, which is often debatable, but for the style, which is reliably lucid.
But it's always a good idea to match the social register and jargon level of the target audience. Professional writers often work on a range of gigs and know how to mould English into a range of styles and voices to reach different audiences.
So I'd be skeptical of any suggestion there's a One True Style for online content or technical writing. There are certainly common standards and traditions, but they may be out of date or too company-specific to apply generally.
In answer to your question, “Handbook of Technical Writing” by Alred et al is good, but I'd start with the first half of “Keys to Great Writing” by Stephen Wilbers, which deserves its Amazon rating of 4.8/5.0.
This might not be so bad as a general guide to writing things like blog posts or whatever, but I'm specifically looking to get better at technical writing - e.g. writing software documentation. For example, the prohibition there on "jargon" words would probably come into conflict with the kind of precision you need in technical writing; I would expect the advice on something like that to be like, "where terms of art are required for the sake of precision, always make sure a definition is available, and link to it in hypertext formats" or "do not overload jargon words".
Don't get me wrong, it's not like there's no overlap, but I'm looking for the equivalent of "Clean Code" for technical writing.
Check out Lyn Dupre's "Bugs in Writing." She was the department editor for Stanfords Biomedical Informatics program for several years and synthesized her work into that book. It's required reading for incoming students.
Yes, I didn't intend that there was a contradiction, just that "jargon" and technical words are actually used more in technical writing than in other kinds of writing, and it can be tricky to understand where the line is, how to introduce these terms such that the reader is not confused by the unusual term (or by a common word used in an unusual way, like how in programming contexts the word "string" refers to a sequence of characters).
Anyway, it's not that none of these principles apply, it's just that there are almost certainly many tweaks here and there and additional tips for people writing technical documentation - for example, almost no one sits down and reads the documentation for a library from "front to back", it is usually used in segments, which has implications about what you can expect your reader to know, and about how important navigation and organization of the document are.
These are just some things that I've noticed as a consumer and producer of documentation, and I don't know that I even have good answers to most of them.
(I hate to make it seem like I'm arguing the point that these more general writing guides are not good, I just want to clarify the kind of thing I'm looking to improve, for myself.)
The IBM book "Developing Quality Technical Information" is the best I've read on technical writing. For writing style, pickup any novel by Hemingway and copy it. You can also Google "how to write like Hemingway" for some easy to follow basic rules.
IMO, however, the biggest problem with most technical writing is not its style but rather the almost complete ignorance of what it should contain and how it should be structured. Open source documentation is a case in point. Some day I will get around to writing an article about documentation anti-patterns, or perhaps a book, given the abundance of examples.
I'd recommend The Sun Also Rises or The Old Man And The Sea for a first Hemingway book. They are both within novella length, so they make for easy reading. Farewell To Arms is probably my favourite, if only because of the last page. Hemingway rewrote it around 37 times because he had trouble getting the words right.
> That said, I really do want to get better at non-fiction writing, specifically technical writing, but I haven't found any good recommendations for "canonical" books on technical writing. If anyone can suggest a decent, pragmatic (as opposed to Strunk-and-White style prescriptivism) introduction to technical writing specifically, I'd appreciate it.
Not a book, but this essay[0] by George Orwell has a number of great tips.
I'm in the middle of reading On Writing Well right now, and have had exactly the same complaint about the examples. There have been multiple examples that I expected him to be using as a demonstration of what not to do, but that he then went on to praise.
I'm still enjoying the book overall and think it has a lot of useful advice, but it's confusing to have so many examples that seem to directly contradict the principles it advocates.
Often recommended, but Anne Lamott's Bird by Bird and Stephen King's On Writing are both autobiographies wrapped in textbook sheepskin. Writing advice that may seem obvious or trite is then backed up with beautiful vignettes.
Good writing is not necessarily good speech, as you've noted. Learning technical writing is a superpower — I would recommend The Essentials of Technical Communication. A chemistry teacher once introduced it alongside a Vonnegut quote:
"It would never occur to me, to look for the best minds of my generation in an undergraduate English department anywhere. I would certainly try the physics department or the music department first."
Technical writing and writing for emotional impact both have their place. Learn both, and learn when to employ them. You may find yourself appreciating that Thoreau quote one day.
> The way he writes makes even interesting topics feel deadly boring.
This sounds like a great endorsement to me. Another complaint I had about Zinsser's book was that he was giving you advice on how to "spice up" your writing, but IIRC (it's been some years), it was all about standard journalistic tricks to construct a narrative, have distinct characters and personalize the story. Obviously that sort of thing is more engaging to read, but I feel like it often distorts the "take-away" message of most scientific and technical writing, given that most science is incremental improvements on existing technology carried out by international collaborations and competitions, not major breakthroughs carried out by lone supermen.
> it was all about standard journalistic tricks to construct a narrative, have distinct characters and personalize the story. Obviously that sort of thing is more engaging to read
That sort of writing doesn't engage me at all. Too many articles begin with something "it was a foggy afternoon as Peter was waiting in line to buy ice cream", taking 5 paragraphs to first touch on the subject mentioned in the title, instead of just coming out with "Scientists recently confirmed that yum yum molecules can generate distinctive taste sensations depending on the amount and color temperature of the light they have been exposed to in the first few hours. This odd discovery began when scientist guy was hoping to grab some cones at his favourite ice cream Parlour in $city, etc. blah blah".
As you can tell, I'm not a writer. But I know the kind of writing I won't waste my time on, and the internet is full of.
Fyi... it was an old style of speaking relevant to Thoreau's time. "Front" was another way of saying "confront". It's wasn't an example of "verbing" a noun in a nonstandard way.[1]
Yeah, I assumed it was something like that, just that if I were writing a book on writing clear non-fiction, I wouldn't use archaic language in my example sentences.
"Avoid unnecessary adverbs - for example, rather than saying 'Forsooth, wherefore didst thou traverse mine bed-chamber?", instead write 'Wherefore didst thou traverse mine bed-chamber?'"
Writing Classic Prose by Mark Turner and Francis Noel Thomas opened my eyes to a different way of thinking about prose style. Instead of focusing on surface features like "avoid the passive voice" and "use adverbs sparingly", it delves into the underlying assumptions of a specific style like the fictional situation (people in conversation), attitude to truth (it's possible to tell the truth about something so you don't need constant hedging), and the audience.
It's well worth reading that book, but it can be a bit repetitive. There's a chapter in Steven Pinker's The Sense of Style that explains classic style more concisely, and also has excellent advice about writing clearly and coherently founded on a more scientific understanding of how grammar and language cognition actually works.
I don't see anything wrong with the sentence besides maybe the use of "front" that you pointed out. I got it easily the first time reading it and I'm certain it would be just as clear to me spoken as long as I was paying attention.
Commas have two roles: syntactic and prosodic. Today, we almost always use them to indicate syntax: separating subclauses etc.
In the nineteenth century, they were commonly used to indicate prosody — breathing pauses and the intended rhythm of the sentence — which leads to comma placements that seem odd to modern eyes but would have been perfectly normal to a nineteenth-century reader. If you read any Jane Austen, George Eliot, or other Victorian writers, you'll see that sort of usage everywhere:
> "It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife."
I highly recommend “Style: Toward Clarity and Grace,” by Joseph Williams. It’s by far the best advice on writing I’ve ever read. I learned about it from Norman Ramsey’s website [1], which has many other good resources. Another good book is the “HBR Guide to Better Business Writing,” by Bryan Garner.
For me, the most important piece of Zinsser's advice is reflected in the complaint and the other complaints in response and in my remark and in the article. They're all in the first person.
"I am eager to improve my language and writing skills."
Fowler and Birchfield. "Kings English" (1906), "A Dictionary of Modern English" (1926) and "The English Language" (1985) make humorous reading. For example:
- Familiar words over the far fetched.
- Preference for concrete words.
- Prefer the single, short word.
- Preference to the Saxon over the romance word.
English has many roots and riddled with confusing syntax and rules. Well written English, shines when read. If you read pg essays you see these examples in action. [0] The Economist style guide mirrors F&B, pg. For instance, "Use the language of everyday speech".
This is my favourite book about writing. It's not only filled with insight but itself serves as a perfect example of what the author is recommending you do.
The Plain English campaign in the UK has some free guides on writing clear and easy-to-read English. Well worth a read whether you are a native speaker or not.
"So what is plain English? It is a message,
written with the reader in mind and with the
right tone of voice, that is clear and concise.":
I recommend Steven Pinker's "the Sense of Style". He talks about some cognitive science behind why some sentences are easier to parse than others.
He also makes a distinction between "classic style" and other styles like "self-conscious style" and technical jargon.
The concept of "classic style" is worth it alone. It's kind of an obvious idea but once you know it, you will look at things you read a different way. It doesn't apply 100% of the time, but it almost certainly does in technical or business communication.
The ability to do anything well co-evolves with finding good reasons to do it. In the case of writing it would be having things you strongly desire to write about.
1) Use what you learned in high school: write in paragraphs with a topic sentence and supporting sentences.
2) After you write a sentence, read it out loud (or pronounce it in your mind) to make sure it flows easily.
4) When people reply to your comments on Hacker News (or Slashdot), try to figure out if they understood what you wrote. If they didn't, next time try to think of a way to be more clear. Over time, you will improve: probably quickly.
If you pronounce it in your mind, you'll pronounce what you thought you wrote, not what you actually wrote. Your memory of your writing will distract from your vision.
The simplest, best, most actionable advice I know to improve writing is: "Edit". The second is "Read it out loud".
> With a little practice, that won't be a problem.
I've written quite a bit of prose over the past decade or so. I still find a lot of things in the third draft (read out loud) that I didn't notice in the first two.
> Imagine you start to write about a topic. Start to think small. “Decide on the corner of the subject you want to bite off.” Cover that corner well, be satisfied by that and stop. Make it a complete experience for your reader. Don’t nibble on another corner of the subject and leave the reader with an incomplete reading experience.
Huh? Shouldn't you provide a birds-eye view of the topic first? Answer questions such as: why should the reader be interested in the topic in the first place, and quickly scan over the relevant issues, make it clear what issue you are going to discuss next, and why.
"make it clear what issue you are going to discuss next"
Please don't. Just get on with it. I routinely skip over anything that does this. Sometimes I have to flip through an entire opening chapter or introduction of a book to get past it.
At least I can skip over it in the written word. When someone is delivering a presentation in the format of "tell them what you're going to tell them, then tell them, then tell them what you told them", it's excruciating.
> "make it clear what issue you are going to discuss next"
> Please don't.
I would agree with you, but you removed "and why" from my sentence, which makes a big difference.
Consider a text about computing. Assume the first chapter discusses the binary number system. If not properly explained why this system is useful in computing, the reader would have a hard time understanding why they are reading about it.
I'm torn. I agree that the three step process you gave is bad. Currently listening to "Search Inside Yourself" and was incredibly annoyed that the first 40ish minutes have so far been about how awesome this practice is and why I should care. To the point that I'm honestly not sure I'll finish the book now. I feel like I'm just being sold something.
That said, often a brief "why" at the beginning would be nice. So, don't just give me a forward of what you'll be telling me. Definitely don't hype it. But, give me some expectation for what I'm listening/reading for.
When I was first working as an author with O'Reilly Publishing (animal books) ~10 years ago they included a copy of "On Writing Well" in the new author welcome kit. I don't know if they still do.
One trick that has been very helpful when editing my books is to use the Mac OS text-to-speech functionality. I find I can catch a lot of typos this way, and rereading multiple times allows me to improve the clarity. Highly recommended!
I haven't updated it in a little bit, but I'm preparing an update that will position it for competitions in local schools & companies, kind of like a spelling bee but actually useful.
There's an amusing number of simple grammatical mistakes in this article.. ("english", "It is unnecessary words that don’t add meaning but complex sentence constructions.", "Write about “grass” except when (my insert) it has another color than green", "Avoid semicolons except when (my insert) you want the reader to make a pause", ...)
In all but one of those examples you're calling out technical errors that don't have much impact on communication.
It seems most HN threads about writing advice have a post nit-picking the article for grammar. I don't see how this is interesting if you don't want to actually make the case that it hurts the author's credibility. Do you?
I found it somewhat amusing, and whilst it did not have a significant effect on my understanding of the article it did break 'the flow' and made the piece much less compelling.
Does this hurt the authors credibility? Yes.
The piece is a summarisation of a book literally called "On Writing Well" yet the text itself shows the author has not fully digested the information they are regurgitating. This is ironic.
That said, it is very well written for a non-native speaker. I would feel much more comfortable having this author communicate on my behalf than many native English speakers that I am close to. With some practice (probably including spoken word and works of fiction) there is no reason they could not exceed the skills of the majority.
The non-native mistakes unwittingly reinforce the point of the article. I found it more readable than many articles having near-perfect grammar and style.
