Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to Be Clear

gilest.org

Post reply on HN
Print view View original

11–20 of 58 posts

Re: How to Be Clear

#11

Post by MaxBarraclough »

munificent wrote: post #10

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 audien…

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

Re: How to Be Clear

#12

Post by hackerbob »

murgaan wrote: post #9

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.

Re: How to Be Clear

#13

Post by coldtea »

murgaan wrote: post #9

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.

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

Re: How to Be Clear

#14

Post by foobarbecue »

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.

Re: How to Be Clear

#15

Post by jcun4128 »

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)

Re: How to Be Clear

#16

Post by brundolf »

gjvc wrote: post #8

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

Re: How to Be Clear

#17

Post by jfengel »

MaxBarraclough wrote: post #11
munificent wrote: post #10

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 audien…

> 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 p…

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.

Re: How to Be Clear

#18

Post by MauranKilom »

foobarbecue wrote: post #14

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

Re: How to Be Clear

#19

Post by wtetzner »

munificent wrote: post #10

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 audien…

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

Post reply on HN