Lessons Learned from “On Writing Well”
robinwieruch.de
robinwieruch.de
"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.
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.
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]
"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?'"
Not a book, but this essay[0] by George Orwell has a number of great tips.
[0] http://www.orwell.ru/library/essays/politics/english/e_polit
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.
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.
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.)
As an aside I like the article How to Write Articles and Essays Quickly and Expertly[0] that was posted here a couple months back as well.
[0] www.downes.ca/post/38526
"The US, a large north-american country,...".
My colleagues and I have read over 50 books about writing and our 11 favorites are here: http://www.conversion-rate-experts.com/writing/
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.
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.
For Whom the Bell Tolls
A Farewell to Arms
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 am a native English speaker and I was confused on the first pass when reading quickly and ignoring punctuation.
Reading slower and taking pauses at the commas allowed me to understand.
I think that minimizing the use of negatives and pauses helps the reader absorb the information quickly.
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 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."
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.
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.
Out of the 250+ books I have notes on, this is in my top 10.
Here are some excerpts from it:
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".
[0] PH Wodehouse ~ http://www.paulgraham.com/heroes.html
"Writing briefly" ~ http://paulgraham.com/writing44.html
"Write like you speak" ~ http://paulgraham.com/talk.html
"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.":
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.
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. If you find it is still a problem, then the solution you gave of reading it out loud is fine, too.
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.
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.
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.
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.
> 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.
Here is how to setup a shortcut key: https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem... (Mac OS X only)
It's an online game gets you away from the stuffy platitudes of books and pits you against other writers to see who can get the message across best.
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.
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?
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.
Personally, I prefer Strunk and White and the AP Style Guide.
But I was looking for good guides for technical documentation, web copy, and B2B high tech marketing material (case studies, data sheets, etc.).
Not how to write a non-fiction book.