HN Books @HNBooksMonth

This guide makes excellent points. I also recommend this book:

https://www.amazon.com/Style-Clarity-Chicago-Writing-Publish...

He says that to achieve clarity, imagine the subject of each sentence as the character of a scene, and the verb as its action. Make sure you hit both character and action within the first 6-10 words of your sentence.

Begin each sentence with information that the reader is familiar with, and end it with the new information you want to introduce.

That will get you a long way toward creating understanding (and feeling) in the reader.

I recently read this book, recommended in another of the infinite posts about writing well, and it is truly good:

https://www.amazon.com/Style-Clarity-Chicago-Writing-Publish...

The chapters from 1 through Cohesion II are better at teaching clarity of thought in writing than any I've read anywhere. Most books focus on grammar and style and ignore the good stuff in between.

For those who like Williams, he also wrote books on how to build arguments and conduct research!

If you read the parent comment with feeling of frustration and dread, ask yourself: "Am I bad at writing a first draft? Or am I bad at editing my writing?". These are two different things.

-----

For learning to edit a piece of writing you've already written, I recommend this book: https://www.amazon.co.uk/Style-Clarity-Chicago-Writing-Publi... It is full of advice more actionable than Strunk and White.

-----

For learning how to write a first draft without wanting to dig your nails into your arms or more drastic forms of self-harm, I recommend:

1) "Start with Why" -- Start each draft by writing your goal and then writing the "signs of success" which you can use to recognize making progress.

I find a particularly motivating form of "why" is a description of a problem someone finds themselves in which they want advice about. Reddit is a good source of these if you want inspiration, but you might be better off giving advice to your future self.

2) Take inspiration from automated testing -- If you are anxious about some section being [maliciously] misinterpreted, write down that anxiety with a pointer to the section and a promise to yourself to have a trusted friend read it.

3) Question-Driven-Drafting -- Start with a question. Write the first flawed answer that comes to mind. Write the first question or objection that comes to mind from that answer. Write the first response that comes to mind from that etc... Don't delete.

4) Alternate focusing with exploring -- Set a pomodoro timer. Use my method from #3 or another to produce a bunch of text. When it goes off, congratulate yourself and meditate for 2 minutes. Then set another pomodoro timer and start to turn your ideas into a structured outline: Try to extract the one-sentence key point from the text you just wrote. Then try to build a pyramid-shaped hierarchy under it with the names of the supporting points. When this pomodoro ends, meditate again and start another rambling pomodoro based on the most interesting point.

5) Be willing to "overthink things" -- When you have a question, be willing to actually trust yourself that the question is worth answering. If someone else thinks the answer is obvious, just move on to ask someone else. If someone screams at you that your question is excuse-making, bullshit, or procrastinating, just move on from them. You no longer have parents nor teachers to endure and can write from your own desire to understand the world and communicate ideas. The confusion you notice in yourself is worthy not of ridicule but of sympathetic curiosity.

6) Go for a walk -- Its just a generally good idea.

7) Dictate into otter.ai -- It is as good a use for your time while walking as any. The resulting text will be heavy with misspellings, but you'll be able to edit it and it will restore your sense of confidence in your ability to generate ideas.

8) Work with a writing coach or therapist if you can find a good one. They might be expensive, but they're less expensive than getting fired because you handed in a blank performance self-evaluation.

One base skill for effective persuasion is the ability to structure paragraphs which convey complex concepts with high clarity and clear emphasis on the important.

A good book on this topic is:

Style: Toward Clarity and Grace (Chicago Guides to Writing, Editing and Publishing) https://www.amazon.co.uk/dp/0226899152/ref=cm_sw_r_cp_api_i_...

Putting together an effective presentation and visual aid (i.e. slide deck) is very time consuming, very iterative, requires a lot of thought and reflection, at least a few reviewers that are removed from putting it together and/or the topic, and a lot of practice. Reducing presentation to simply putting together a slide deck is a fail from the get-go. Blaming bad presentations on the tools used to put them together is shallow.

While there is really no substitute for good coaching, first hand experience, mistakes made and good feedback, here are a few quick tips that I've picked up over the years -

1. The best and most engaging presentations simply have a title that captures the key point and a nice/fun background photo that supports/illustrates the story. Audience will pay attention to the story instead of reading text off the slide.

2. To highlight a fact, keep it to one fact per slide. Make it short and direct (e.g. "3x faster" rather than "212.32% performance improvement").

3. To illustrate a quantitative point, one chart per page is okay, but it must be super simple and easy (absolutely no 3D nonsense, at most 3-4 bars/2 lines/3-4 pie slices, clearly labeled axes). Multiple charts are sometimes okay, but they must be each super simple, belong together, have the same scales and tell a clear and obvious story. Effective charts are a topic of its own, anything by Tufte is a great head start.

4. If you must have more than one point on a slide, keep it at 3 direct, concise bullets per page (if any bullet wraps with a large font, it's too wordy and unclear). No sub-bullets or additional explanations should be necessary. Two bullets is too little (i.e. condense it to one key point), four is too much.

5. No more than one simple diagram per page. Best to keep it to the title that captures they key point and a diagram. Additional explanatory text should not be necessary - if title + diagram can't stand on their own, they are not good enough. Also, if the point of the diagram is not immediately obvious to someone looking at it for the first time, the diagram sucks.

6. Avoid wall of text (e.g. that NASA slide on Columbia's tiles) at all costs. Audience will start reading the slide, completely tune out what you are saying and then get bored half a way through and give up.

7. Contrasting points or showing contradictory data/ideas requires extra care to avoid cognitive dissonance.

8. Background should be as plain as possible. White is best, black/gray could be okay. Anything else pretty much sucks. All text in one color, with great contrast to the background.

9. Timing/length of presentation is super important. Generally, it is very hard for people to stay focused for more than ~7 minutes, so it's good to cover a point in less than 7 minutes and then change it up a bit (e.g. change presenters, show a video, get to a different topic). Overall, presentations should be less than 30 minutes, 45 minutes tops. Anything longer than that is simply too long, you'll lose the audience. Here are two books on the topic I found helpful. They are easy to follow, very short and to the point - "Style: Toward Clarity and Grace" [1] and "Guide to Managerial Communication" [2].

* * *

Overall, the piece feels quite trashy - it dumps all the blame where it doesn't belong (tool vs. lack of presentation/communication skill). Those slides could have very well been made in Keynote or Reveal.JS and they wouldn't suck any less. The piece is also not constructive, it doesn't give reader any hints or tips how to make presentations better.

Finally, a great counterexample to the main point of the piece is pretty much every slide deck that comes with Apple/Steve Jobs' keynote. The best part is that no one remembers or pays particular attention to the deck, but if you analyze the presentation more closely or watch it a couple of times, it becomes clear how effective the decks are.

[1] http://www.amazon.com/gp/product/0226899152

[2] http://www.amazon.com/gp/product/013297133X

Great article. While I agree that writing skill is incredibly important, I disagree with Mr. Tan's advice to just 'write lots and keep reducing your text' as the best way to go about writing clearly.

I certainly didn't learn how to write clearly at University and I had to write loads of reports and essays for 5 years.

I actually owe a great debt of gratitude to my first job out of University where I worked as an analyst for a finance and economics consultancy. The CEO was fanatical about making everything Plain English writing style. It was a trial by fire.

Anyway, my advice is to go on a Plain English writing course. The course instructors usually critique your writing and offer helpful insights on how to improve. If that's not possible, go through the guides on the Plain English website (http://www.plainenglish.co.uk/free-guides.html). I also highly recommend applying the writing principals in Style: Toward Clarity and Grace (http://www.amazon.co.uk/Style-Clarity-Chicago-Writing-Publis...). This book is worth its weight in gold.

The best book I found on writing succinctly is Joseph M. Williams' "Style: Toward Clarity and Grace". I highly recommend it!

http://amzn.com/0226899152/

Here is a well-reviewed book on this topic:

    http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishing/dp/0226899152/

From the editorial reviews:

"Telling me to 'Be clear,' " writes Joseph M. Williams in Style: Toward Clarity and Grace, "is like telling me to 'Hit the ball squarely.' I know that. What I don't know is how to do it." If you are ever going to know how to write clearly, it will be after reading Williams' book, which is a rigorous examination of--and lesson in--the elements of fine writing.

⬐ pseut

This link goes to an older edition of the book; it's since been split into a short version ("basics of clarity and grace") as well as a longer version ("lessons in clarity and grace") -- the longer version has exercises (I think) and the shorter one doesn't. I own the shorter version and haven't felt a need to look at the longer one.

In any case, this book is great and helped me immeasurably in writing my dissertation in grad school. It gives some advice on sentence structure that I haven't seen elsewhere (like when and why the passive voice can be useful) but also gives a lot of "formulaic" advice on how to organize the entire document. I say "formulaic" because he essentially gives you a formula, which is exactly what I needed and seems to be what you're asking for.

FWIW, I own or have read well over 30 books on writing and this is easily the best one on general---i.e. subject-agnostic---writing.

⬐ urlwolf

Williams' book is all that 'Skunk and White' should have been. Consistent, actionable, readable.

⬐ rhizome

And contrary to the OP's assertion, there is no "missing trick" here.

⬐ Paul8

Joseph M. Williams's "Style: Toward Clarity and Grace" is by far the best book on learning HOW to put sentences and paragraphs together. It teaches principles that I've never seen anywhere else -- principles for making my writing easy to understand.

Then it teaches methods for applying those principles.

So instead of teaching rules, it teaches how writing can be clear. Instead of "don't use passives" it shows when a passive verb makes the writing easier to read. It teaches how much new information to put in a sentence and where to put it. And it shows how to connect this sentence to the next for simple flow.

If you're willing to spend a few dollars to improve your writing, buy "Style: Toward Clarity and Grace" by Joseph Williams (http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishi...). It's far better than a list of rules; it breaks down sentence and paragraph construction and shows you exactly how to write more clearly (and less academically). And it accomplishes this very quickly, with a marked improvement in your writing after only a couple chapters.

I love "Clear and Simple as the Truth" for a very authoritative voice which can present complex things without dumbing down: (Non-aff) http://www.amazon.com/Clear-Simple-As-Truth-Writing/dp/06910...

And "Style: Towards Clarity and Grace" for a more humble, direct, simple style for non-complex presentation: (Non-aff) http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishi...

⬐ tptacek

Every time I've reread _Style:_, I'm struck by how agreeable its mindset is to hackers. It's no wonder Richard Gabriel liked it so much. It's practically a hacker's guide to better writing. Highly recommended.

Oh hi there, forgot this is a small world we're in and you might actually read my comment. You're a good writer most of the time, however, I believe you're trying to use a certain style here, and that style may not be appropriate for this type of work if you are aiming at adults and children both; it is appropriate for a children's book though.

The patronizing part wasn't the non-programmer part and making fun of programmers. I actually loved the line about VI/Emacs. It was the overly simplified sentences. Let me dig the pdf out:

You can print things out with print and you can do math. The next step is to learn about variables. In programming a variable is nothing more than a name for something so you can use the name rather than the something as you code. Programmers use these variable names to make their code read more like English, and because programmers have a lousy ability to remember things. If they didn’t use good names for things in their software they’d get lost when they came back and tried to read their code again.

For instance in this section your actual sentences are very simple. Over and over you use these simple sentences. And you use an explicit "you". It gives the feel of a children's book (I don't know if you have kids, but if not, google for some of the books or ask a co-worker to borrow some). I think explicit "you" is fine, but the constant reassurance compounded with the sentence structure and explicit "you" feels patronizing.

Other examples:

You might not know it, but every time you put " (double-quotes) around a piece of text you’ve been making a string.

Most of these concepts will be exciting once you get them. You’ll struggle with them, like wrestling a squid, then one day snap you’ll understand it.

I know several people professionally who'd benefit from the book if you upped the "implicit respect" of the style a few notches. However, I'd be afraid to give it to a few of them out of fear of insulting them with the way some people will interpret the tone. I'm putting this out there in all earnestness.

Here are a couple books on two different styles which might be more applicable for the work. They are on actual explicit styles of writing, although the second pretends all writing should look like that.

Clear and Simple as the Truth by Thomas & Turner (Classic style).

Nonafflink: http://www.amazon.com/Clear-Simple-As-Truth-Writing/dp/06910...

Example of classic style:

When I was a boy, there was but one permanent ambition among my comrades in our village footnote [1. Hannibal, Missouri] on the west bank of the Mississippi River. That was, to be a steamboatman. We had transient ambitions of other sorts, but they were only transient. When a circus came and went, it left us all burning to become clowns; .... now and then we had a hope that if we lived and were good, God would permit us to be pirates. These ambitions faded out, each in its turn; but the ambition to be a steamboatman always remained. --Mark Twain

Style by Williams (Plain Style):

Nonafflink: http://www.amazon.com/Style-Clarity-Chicago-Writing-Publishi...

Example: After Peter the Great died, seven out of eight reigns of the Romanov line were plagued by turmoil over disputed succession to the throne. -- Williams edit to uncredited work on Russia

⬐ zedshaw

That's only patronizing if you take yourself too seriously. Otherwise it's just direct and simple. That makes it easier to read and makes sure that the prose doesn't make things seem more complex than they actually are.

Another way to put that is the complexity/simplicity of the prose attempts to match the complexity/simplicity of the exercise.

⬐ gte910h

It's not me I'm worried about it coming off as patronizing to.

I'm worried about people I might recommend it to (and thereby seem patronizing myself). With the current style, I'd probably only recommend it to kids and a couple adults I know very very well.

Encouragement and assuming the user only knows what you have told them (which you do in a few places) are the things that don't come off as "adult literature". Hell, a couple teens I know would feel patronized by that, and teens definitely take themselves seriously. The short sentence structure is only the biggest of deal because of the other two facets. You could keep your grade 6 FKA score but ditch the other two parts of the style.

As the tone is now, I'm pretty sure they'd take me handing this to them worse than a X for dummies book.

⬐ Radix

Why can't you simply deride the language while praising the approach. Then the adult can believe you aren't being patronizing, maybe the book is, but the book is an effective way to learn. The teenagers can run through it in a short time (or read through it if they should be reading another book), and the adults will be fine. Have you heard how many adults say "oh I'm not very good with computers"? What's there to be good with?

Not that the book is worth derision, just as a tactic for those who take themselves too seriously.

⬐ gte910h

As I said before: >It's not me I'm worried about it coming off as patronizing to.

I know Zed's history. I'm not going to have issues using the book. But random non-programmers don't. And those are the people I'd hand the book to. I've got a thicker skin than some of them, and wouldn't care about the tone of the tome even if he directly insulted me. But THEY would. That's the issue.

⬐ jordyhoyt

You aren't listening. He said to, "deride the language" and "praise the approach" to those you give the book to.

i.e. When you hand it to them, say, "the language is overly simple and patronizing, but his approach is a good way to learn." Then your (apparently) big-ego friends can mantain their air of superiority while reading the book, without being insulted.

Not that I agree that his language needs to be changed; on the contrary I think is is great. I would have loved such a gentle introduction, at any age.

⬐ gte910h

They're not friends who I'd hand the book to.

They're certain people at companies I know and work with professionally who ask me "Hey gte910h, what's a great way to learn programming".

I'm known as respectful yet blunt. If I handed this to someone, they'd wonder if I was saying they came off as retarded or that I had no respect for them (or programming is much harder than it is for the type of tasks they want to do).

For people who work in relationship based businesses (many non-programming businesses are), what others think about you is very important. The idea I thought them incompetent would be a very bad thing.

Some of the people I'd hand a book that went through the typing approach without the coddling part would hear the book loud and clear and possibly not remember the message I could use to hand them the book: "Hey, this guy who tends to be a bit insulting to people in some of his writing wrote a book on programming. He acts like you're a dull 11 year old throughout the book. But hey, his method is good".

These aren't people with big egos, but I'd sure as come off as having one about my profession if I tossed this at them. Especially if they handed it off to a third person who I never met but had heard of me.

I'd just be more respectful and less helpful and not ever mention the problematic resource. It's not worth the risk I'd lose a client over it.

>You aren't listening. He said to, "deride the language" and "praise the approach" to those you give the book to.

It wasn't clear to me the poster was talking about those you give the book to. It just sounded to me like he wanted me to give props to Shaw for his approach while saying he wrote in a manner some would take offense to.

As to Zed Shaw, I think I've honestly put in more work on the book already than 99% of the people who love it unconditionally have. I've read it in it's entirety and given suggested changes. Editors and critics are very useful when writing books.

He doesn't need to change the style. If he changes the style, he can market it as a book for adults and children. If he keeps the style the same, he should market it as a book for 12 year olds. Then, when someone hands a copy, it says right there on the cover "Yo, this is for kids" and no one get's insulted as you can reveal "Hey, this is really good, in spite being for 12 year olds".