
Lessons Learned from “On Writing Well” - rwieruch
https://www.robinwieruch.de/lessons-learned-on-writing-well/
======
liangzan
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.

~~~
BaronSamedi
I completely agree. "Style" is a great book--short and practical.

~~~
ChristianGeek
Why is it so expensive?!

~~~
techer
Look at the used previous editions...

------
x1798DE
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.

~~~
cgh
I'm sure you've seen it before, but The Economist's style guide is my usual
resource:
[http://www.economist.com/styleguide/introduction](http://www.economist.com/styleguide/introduction)

~~~
x1798DE
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.

~~~
blisse
But the rule is to avoid jargon if there's a better everyday equivalent, not
to avoid jargon at all costs. There's no contradiction.

~~~
x1798DE
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.)

~~~
blisse
No problem. I really enjoy MSDN documentation so I think imitating good guides
or tutorials is a good starting point.

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

------
sivers
Amazing book.

Out of the 250+ books I have notes on, this is in my top 10.

Here are some excerpts from it:

[https://sivers.org/book/OnWritingWell](https://sivers.org/book/OnWritingWell)

------
bootload
_" 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"_.

[0] PH Wodehouse ~
[http://www.paulgraham.com/heroes.html](http://www.paulgraham.com/heroes.html)

 _" Writing briefly"_ ~
[http://paulgraham.com/writing44.html](http://paulgraham.com/writing44.html)

 _" Write like you speak"_ ~
[http://paulgraham.com/talk.html](http://paulgraham.com/talk.html)

------
lunchladydoris
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.

~~~
panic
Yeah, the examples in the book are almost unnecessary next to its own text.
You can tell how much work Zinsser put into every phrase.

------
open-source-ux
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."_:

[http://www.plainenglish.co.uk/free-
guides.html](http://www.plainenglish.co.uk/free-guides.html)

~~~
combatentropy
Cool! The U.S. has an informal group for federal employees:
[http://www.plainlanguage.gov/](http://www.plainlanguage.gov/)

------
chubot
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.

------
umberway
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.

------
ktRolster
For the lazy, here are my tips:

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.

~~~
munificent
> read it out loud (or pronounce it in your mind)

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".

~~~
ktRolster
_If you pronounce it in your mind, you 'll pronounce what you thought you
wrote, not what you actually wrote_

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.

~~~
munificent
> 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.

~~~
ktRolster
ok, keep it up then :)

------
amelius
> 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.

~~~
EliRivers
"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.

~~~
amelius
> "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.

------
kkielhofner
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.

------
ivan_ah
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!

Here is how to setup a shortcut key:
[https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem...](https://docs.google.com/document/d/1mApa60zJA8rgEm6T6GF0yIem8qpMmnaBFYOgV32gdMc/edit?usp=sharing)
(Mac OS X only)

------
m52go
Plug: if want to write crisper, try my game, Worrd Warrior.

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.

[http://worrdwarrior.com](http://worrdwarrior.com)

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.

------
idlewords
Just go read the Zissner book. It's worth your time.

------
cachvico
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", ...)

~~~
aggie
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?

~~~
Normal_gaussian
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.

------
WhiteSource1
I was recommended Zinsser from a writer whose own writing is very wordy.

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.

