How to Be Clear | Hacker News Reader

How to Be Clear

gilest.org

195 pointshypomnemata56 comments

Tangentially, this is obviously targeting business or team communication and it's a great collection of practical advice.

It made me wonder what the corollary rule set would be when writing fiction. The advice: "Always start by thinking about what you want an audience to understand, know, or do after they’ve seen a piece of communication," could be expanded to include 'feel' or 'envision' or 'wonder'. In some ways, it would call for de-tuning the precision and intentionally introducing vagueness, demotic or evocative language.

Much science outreach and popular media prioritizes "engagement" and "interest", above understand/know/do.

I recently wondered if one might get more "understand", by authoring content with an added objective of setting up the reader/viewer to "do" bite-sized storytelling - with friends, family, water cooler - thus perhaps both broadening impact, and adding motivation towards understanding.

Fun frame.

So... Viral content?

Viral storytelling? Hmm, there's a thought. So one challenge with designing a story to be told, is how to make it stable. Else it becomes a source of misconceptions, rather than of understanding. If the story is then passed on further, that becomes the telephone game, and stability... becomes even harder. Status quo disinclination to pass on (pervasively flawed) understanding does have benefits. So what if it were paired with a bit of traditional viral content, to provide a stable reference? How might one get the two, oral storytelling and viral content, to propagate together? Perhaps if the setup for storytelling was itself the viral content? Somehow search keyed so someone in receipt of only the oral, could recover the viral? Or if the viral had additional value, perhaps compelling video, so there was incentive to present both? Hmm. Fun morning brainstorming - thanks!

Might an example for this community be xkcd links?

Oh, nice example. I wonder if repackaging a viral content of '<meme>' as a conversational cartoon, 'A: "<meme>!" B: "LOL!"', might increase the likelihood of it being spoken? Perhaps yielding viral content spread, with oral storytelling leaves. Or maybe even A: "<idea>" B: "Neat! <question>?" A: "<answer>" to scaffold further conversation and thought?

There's a common professorial comment, that they didn't really understanding some topic, until after preparing for, and teaching it. So the exploratory question is, how might 'preparing for, and teaching it' be made a greater part of the science education content and outreach experience. For the additional motivation of sharing the knowledge with others. And for the incentive towards clearer, more integrated understanding - eg, to be able to answer non-toy real-people questions.

This is a great opportunity to talk about the worst-written sign I have ever seen.

The "slippery when wet" signs at Atlanta Hartsfield-Jackson International Airport read:

** Caution Please be careful while using the restroom. For your safety, we remind you that flooring can be very slippery when wet.

Your safety is our concern. **

https://imgur.com/Uh9DrLh

These make me so irrationally frustrated. Why do they use such flowery language? What purpose does that serve? There's no call to action, how does it improve the user experience?

There is no purpose to these signs aside from limiting liability in the eyes of the court system when you slip and fall and sue them. It's similar to the signs that say no trespassing.

Ya, it should just read "slippery when wet". Maybe add an exclamation mark to show urgency and that you care.

So how we would describe the sign is usually what it should say. Like, "STOP".

Or in this case "Caution" which usually is the largest text on these type of signs. Caution and some indication they are referring to the floor, which could just be contextual. The queue that these signs are often short will natural indicate the eye to look at the floor, so that is nice when it works out.

I'm personally not a fan of the author's writing style. You can fetishize minimalism and clarity to the point that it undermines your goal. But the content here is good. In TODO list form, I suggest anyone writing something think through:

1. Who are you writing to?

2. Why are you writing to them?

3. What do you want them to know?

4. What do they already know?

5. What style of writing is most effective for this audience and intention?

What remains is to use 5 to describe the difference between 4 and 3 in order to accomplish 2. The primary challenge is that 1 is often not a single person and the wider the audience you choose, the fuzzier all of the subsequent answers become. The single best thing you can do to become a stronger writer is to be courageous about selecting a narrow audience.

> I'm personally not a fan of the author's writing style.

Agreed. The paragraphs are too short and are not as freestanding as they should be. For instance the following should have been folded into the preceding paragraph, which provided the vital context:

> But that’s often the cause of the failure.

I also find it jarring to read a sentence beginning with and or but, although not everyone agrees with me that it's poor style.

I find myself beginning sentences with conjunctions. I try to edit it out most of the time, but I'm not fanatical about it. I think it reads more clearly to the original writer than it does to a reader.

You're absolutely correct about the paragraphs. A paragraph is a tool for organizing your document. If you have only one sentence per paragraph, you're sacrificing that tool. You already have the period to separate sentences, so you should use paragraph separators to group sentences into a coherent thought.

The rule of thumb is 3-5 sentences per paragraph. It's not ironclad, but if you find yourself breaking it often, you're probably doing something wrong.

There is a specific case where you start a sentence with 'but': when you want to give someone time to accept the previous statement before demolishing it. This is what we all know, and we all agree that we see it. But what we know is not right, and here's why.

If a person is using And and But equally, they just like the mental pause between their statements. The period is more of an ellipsis. If your reader needs a mental pause before an And, before a second piece of information, maybe your information is too dense and you should free the new information to stand alone. Possibly in a new paragraph.

As in, "The other thing that's cool about this process is that it also does blah. Which is useful for these reasons..."

I don't know how other people develop a theory of a system, but if you want to change mine, if I want to change mine, I have to 'walk into it' see what's wrong with it, deconstruct it and put it back together the new way. If you don't bring me through this, I'm going to make you stop talking, back up, and walk me through it anyway. Otherwise your next best outcome is that later than night when I'm brushing my teeth I realize you're right and we pick it back up tomorrow. If it's in writing, I can only make you back up by skipping back a few paragraphs, or writing a response that you may or may see. If your proposal is too woo, I'll just be writing you off entirely.

> 4. What do they already know?

Yeah, I've found that this is what's most commonly overlooked when communicated with people at work. They either spend too much time explaining things you already know, or assume context you don't have.

It’s not always easy though to get a good idea of where people currently are on a potentially decades-long multidimensional learning curve. You need a back-and-forth dialog to home in on the right level.

It may not be easy, but I think it's the area that needs the most focus, at least at my company.

I very much prefer when they explain too much than too little. Yeah, it might be boring to listen to or you might have to skim a big part of the text, but that is much better than being lost.

In text I don't mind so much, but in meetings it can waste a lot of time.

I can’t agree enough on this point. It wastes so much time to overexplain things every time they come up. It doesn’t matter as much until it’s senior people communicating with one other, at which point you can save countless minutes/hours by just trusting each other to be competent on the subject. This is why you should just ask questions when you don’t understand what someone is talking about— let them give you the quick version assuming equal competence, but ask when you DO need clarification. It not only saves time, but builds trust.

Sorry this turned out being less about writing and more about communication in the workplace.

Your list is a much easier read, and consequently a far more effective communication than the article.

The last two sentences are not required and could be omitted for clarity, or at least truncated beyond the conjunction "and" in sentence two of your last paragraph.

Advance apologies for coming across strong, but for an article advocating clarity, it is utterly devoid of an examples of how to actually achieve it. If your title starts with "How to..." you should SHOW, not TELL, and the article was a whole lot of telling. And the one example that was accidentally there - the image at the top - did not clarify if it was a good one or not (see discussion here, for example).

Others have found issue with the grammar and sentence structure of the article, I found it totally opaque.

Show me an example of a mental model (or the absence of one). Pull an excerpt from the Times or the economist and contrast it with another publication that is not clear. Wouldnt this help us "understand, know and" eventually "do"?

And given that the advice is to think about your audiences and communicate with purpose, please do ask yourself: What is the purpose of this article? If it's to tell us to strive for clarity, please show us how, don't just tell us to do so.

Is "PLEASE REMEMBER TO PARTIALLY CLOSE THE SHARPS BIN" supposed to be an example of doing this correctly, or incorrectly? I find the notice unclear, but it's also unclear what point the author is trying to make by using this image.

The fun part is that this depends entirely on the audience. Not only the demographic, but also what prior instructions they received.

Seeing that sign without further context, I assume this is a bin full of sharpies (could be wrong), and that it is supposed to be left slightly open. How closed "partially" closed is I would have to guess.

But if this is for a group of students in an art class that have all been clearly instructed how to handle this bin (see "remember to"), it might be the perfect reminder. Meaning "Close it to the degree you've been shown in the first lesson".

I know this is beside the point... It’s a bin for medical waste in the form of things that can break the skin. Used needles etc. It’s a special bin that once completely closed is intentionally quite difficult to open again.

„Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible.” (from: The Economist Style Guide)

I recommend the whole Guide wholeheartedly.

Not really commenting on the guide, but for me, clarity of thought follows writing. Not the reverse.

Yup. For me the process is something like:

1. Think that I know something.

2. Write about it. Realize I didn't know it anywhere near as well as I thought.

3. Reflect on and actually understand thing.

4. Edit writing now that I actually know what the hell I'm talking about.

And further than that, even if when do know most the pertinent details, the best way to communicate them is probably not the jumbled order it appears in your head, nor is it even some "logical" order (such a timeline or logical argumentation).

Writing for clarity often involves careful consideration of how to sequence the information such that it can be consumed given the audience and knowing when to elide details or otherwise footnote them.

Same, I usually end up writing anything important twice because the first draft is when I realize all of the things I hadn't thought through.

The MIT OpenCourseWare talk How to Speak by Patrick Winston is a great lecture on this subject: https://youtu.be/Unzc731iCUY

"Think about what your readers might already know."

This alone is an excellent starting point. You know the feeling of dismay when someone starts talking beneath your level of understanding and you fear they'll never go above it? Thinking about what your audience (written or spoken) might already know is the intelligent, considerate, and efficacious thing to do.

And the opposite is exceedingly frustrating: when someone starts explaining something in terms of base concepts you've never even heard of, and you have to stop them every few seconds to fill in the blanks (and then some of those explanations have holes of their own, etc). In some cases you may be so new to a topic that you don't even know which questions to ask, so it's impossible for you to shepherd them into telling you what you need to know.

This is when I find good teachers/explainers switch to analogies - however imperfect they might be.

I'm writing a primer on music theory, and I have this same fear. I resolve it in three ways:

1) I try to make the writing entertaining enough that people won't mind reading something they already know

2) I added an anchor tag saying "click if you already know this stuff"

3) I added tooltips explaining vocabulary words, so if you skipped a section and end up not knowing everything you thought you did, you can use the tooltips to refresh your memory.

These three factors I think combine in a really nice way. I'm excited to post it here when I'm done with it.

Excellent post. I should add that text formating is almost as important as what you want to say.

11 short sentences addressing 4 points packed in a single paragraph is really painfull to read.

Use paragraphs, new lines and bullet points as much as you can.

Let the reader breath.

This makes me sad. Instead of educating ourselves, we're supposed to give up and write for the lowest common denominator, whose reading skills continue to erode. I don't need my technical documents to read like DFW, but let's not take all the fun out of it.

It shouldn't. Everyone's time should be respected. Clarity and conciseness in writing or in speech is a great way to show that.

I think those are two separate matters:

Indeed the average reading skills seem to continue to erode (or, at least, attention spans have been shown to decline, the Flynn effect has stalled, and functional iliteracacy of supposedly educated people is at an all times high)

... but we still should strive for clarity, whether we're addressing the average Joe or DFW (perhaps you've meant EWD?).

Dislike authors writing style.

Here’s an excerpt with bad grammar:

— If you’re struggling to picture what clear writing looks like, buy a copy of the Financial Times or The Economist. Pay attention to the way articles their are written, to the word choices and sentence structures. —-

Ironic

What's wrong with that excerpt? How would you improve it?

> If you’re struggling to picture what clear writing looks like, buy a copy of the Financial Times or The Economist. Pay attention to the way articles their are written, to the word choices and sentence structures.

Try the Financial Times or the Economist for strong, clear writing. In particular, pay attention to their word choice and sentence structure.

I did notice it's easy to mislead/derail people trying to help you by not being clear... I always feel awkward when that happens.

(context of debugging)

> Write shorter sentences, with simpler words

What is the urge to write shorter sentences? Short sentences are akin to verbose code in a language like Java. Every new sentence you write must include the essential components of a sentence, the skeleton, for it to be grammatically correct or in Java:

  public static void method1(String[] args)
  public static void method2(String[] args)
  public static void method3(String[] args)

This is wasted effort that could have been saved if one was to simply reuse the same sentence to add more nuances to it. After all human languages are extremely powerful and the mere fact that it is possible to compose complex sentences is a sign that some found them more advantageous. An average German sentence is probably 2 or 3 times longer than an English one, I think this has more to do with the users of the language than the language itself, if true it means we can make English pack more punch we just have to change our perspective. I love minimalistic code but it doesn't mean code that doesn't do much, minimalism means packing as much into as little as possible, the final result after adding all sentences will be significantly shorter compared to if single-purpose-shorter sentences were used.

It's also the same type of religiosity with unit testing and TDD that turns codebases into monstrosities and shift focus away from understanding to mere correctness. Non-nuanced sentences in the form of tweets and their corrosive impact on culture and communication are probably another adverse side effect of this devoutness to shorter sentences.

I wouldn't typically nitpick grammar on this site, but I believe you're trying to demonstrate a point and I want to refute it.

>> An average German sentence is probably 2 or 3 times longer than an English one, I think this has more to do with the users of the language than the language itself, if true it means we can make English pack more punch we just have to change our perspective.

Grammatically speaking, this should be three separate sentences. Your commas should be full stops because they represent three separate thoughts. You could connect them with 'and', but I'd suggest most native speakers would find this unpleasant to read.

I don't want to make it sound like I'm not a fan of long sentences - I think fiction writing benefits from a varied cadence. For business writing, however, I think short- or medium-sized sentences are less intrusive to the average reader.

I suspect most non-social-media writing more often suffers from longer, more complex sentences than those too short. The programing analogy might be cyclomatic complexity and separation of concerns. Examples abound of functions with overloaded conditionals, long parameter lists and other smells that might it difficult to reason about the operation of such a function. On the other-hand, you do see the overzealous craft trivial functions that should just be inlined in the few places they are used.

Clarity, for both prose and code, involves finding the right tradeoffs and abstraction boundaries.

Clarity and brevity are good, but when everyone is focused, no one is talking. Silence is the sound of everyone working. Talking can be a symptom of mismanagement.

Also, better English won't help when the goal is to dodge work or responsibility, which is often what's behind miscommunicating team members. A well spoken excuse is still a poor excuse.

Maybe start by writing a better headline? Clear about what? Does it show me how to be as clear as a piece of glass? ... sigh

This advice is for getting people to understand without much thinking. That's not always the goal.

Clarity in (argumentative, essay, etc) writing is taking upmost care of your reader: you want to hold the hand of the reader and guide them towards a new understanding with little to no strain.