Hacker News Reader

"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 also important to note the difference in how text is consumed online vs in a book.

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.

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.

I agree. I struggled through Zinsser and didn't highlight much.

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.

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

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.

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.

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

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

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.

Try this one [0]. It's written by the CEO and Lead Writer of iFixit.

[0] - http://www.dozuki.com/Tech_Writing

Every time I read the Economist I wonder if their apparent compulsion to explain everything is some sort of in-joke.

"The US, a large north-american country,...".

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.

Can you recommend some hemingway books?

The Sun Also Rises

For Whom the Bell Tolls

A Farewell to Arms

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.

[0] http://www.orwell.ru/library/essays/politics/english/e_polit

I think http://slatestarcodex.com/2016/02/20/writing-advice/ is not really what you're looking for but is on the same continent.

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.

Agreed. Improving my writing from countless essays and writing heavy classes has been a tremendous help in my life.

I enjoyed (the first 2/3 of) Steven Pinker's The Sense of Style. It includes examples of where prescriptivism fails and succeeds.

Surprising to see Pinker has written a book about writing. The way he writes makes even interesting topics feel deadly boring.

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

He also has a YouTube video which is a great intro to his thoughts on writings.

https://www.youtube.com/watch?v=OV5J6BfToSw

>, with a non-standard use of "front" as a verb

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]

[1]http://www.gocomics.com/calvinandhobbes/1993/01/25

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.

I remember this story and the only (personal preference) issue I can take with it were the comma placements. Yikes. Shatner anyone?

I think the commas very well placed. If it reads like Shatner to you, then perhaps you are reading as if they were ellipses?

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.

[1] http://www.cs.tufts.edu/~nr/students/writing.html

I enjoyed "Writing that works".

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.