[HN Gopher] How to Be Clear
___________________________________________________________________
How to Be Clear
Author : hypomnemata
Score : 115 points
Date : 2021-01-28 16:18 UTC (6 hours ago)
(HTM) web link (gilest.org)
(TXT) w3m dump (gilest.org)
| murgaan wrote:
| 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.
| hackerbob wrote:
| It shouldn't. Everyone's time should be respected. Clarity and
| conciseness in writing or in speech is a great way to show
| that.
| coldtea wrote:
| 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?).
| [deleted]
| jcun4128 wrote:
| 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)
| tzmudzin wrote:
| ,,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.
| FPGAhacker wrote:
| Not really commenting on the guide, but for me, clarity of
| thought follows writing. Not the reverse.
| munificent wrote:
| 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.
| munchbunny wrote:
| 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.
| throwawayboise wrote:
| Related to this topic, from 2017
|
| https://news.ycombinator.com/item?id=14808374
| 11thEarlOfMar wrote:
| 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.
| cambalache wrote:
| "Resist the urge to appear smart"
| pattisapu wrote:
| "I quite agree with you," said the Duchess; "and the moral of
| that is -- `Be what you would seem to be' -- or, if you'd like
| it put more simply -- `Never imagine yourself not to be
| otherwise than what it might appear to others that what you
| were or might have been was not otherwise than what you had
| been would have appeared to them to be otherwise.'" -- Lewis
| Carrol, "Alice in Wonderland"
| 50 wrote:
| 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.
| gjvc wrote:
| "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.
| brundolf wrote:
| 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.
| sylvainr65 wrote:
| 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.
| ape4 wrote:
| For the sharps bin a diagram or icon would be useful.
| munificent wrote:
| 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.
| wombatmobile wrote:
| 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.
| wtetzner wrote:
| > 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.
| Ma8ee wrote:
| 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.
| layer8 wrote:
| 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.
| wtetzner wrote:
| It may not be easy, but I think it's the area that needs
| the most focus, at least at my company.
| MaxBarraclough wrote:
| > 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.
| jfengel wrote:
| 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.
| hinkley wrote:
| 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.
| glacials wrote:
| The MIT OpenCourseWare talk _How to Speak_ by Patrick Winston is
| a great lecture on this subject: https://youtu.be/Unzc731iCUY
| drewcoo wrote:
| This advice is for getting people to understand without much
| thinking. That's not always the goal.
| foobarbecue wrote:
| 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.
| MauranKilom wrote:
| 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".
| FPGAhacker wrote:
| 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.
___________________________________________________________________
(page generated 2021-01-28 23:01 UTC)