111–120 of 168 posts
Decent post but we just saw this yesterday. https://news.ycombinator.com/item?id=28246519
two points and no comments doesnt count as a duplicate on HN, so please don't point cases like that out. https://news.ycombinator.com/newsfaq.html
One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…
Not only do you have the problem of different 'it's referring to different things, I think there's also an element of adding unnecessary cognitive load at a time where cognitive load is already high. Even if there's only one pronoun and one possible thing that the pronoun could refer to, your brain still needs to do the cognitive lookbehind to interpret the sentence.
One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…
It can also be used to make text easier to understand, for example: The client connected to the server, then it crashed vs The client connected to the server, then the server crashed.
Okay, it's obvious to you that the client didn't crash (but should it be obvious? Clients can crash too, you know!), but for anyone who didn't make the right inference, or isn't sure, they now have a dangling node in their mental model and are still validating they understood it right as they read the next sentences.
If you really can't stand such repetition, go with "then the latter crashed".
One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…
Unfortunately, I consider that itself annoying because it then creates the problem of assuming your reader knows which of those are just alternate phrases vs other entities in the story!
Side note: this story got reposted twice recently so my comment on one of them (with examples of me producing a better explanation than the ones I had to wade through) got neglected: https://news.ycombinator.com/item?id=28241558
[1] Oops, another anti-pattern -- saying "this" or "that" when it's not clear what you mean. Here I should have said "this problem" -- it's a great technique for clarifying your own thoughts as well!
> having inconsistent expectations of the reader’s knowledge I come across this one the most and suspect it's the most common reason people suddenly stop following an explanation. Whether it's in a book or a Wikipedia article. I guess when the author already knows something, it's a difficult skill to maintain the full perspective of the audience - some things they obviously don't know and are easy to explain, so they…
Wikipedia maths articles are really bad for that because articles are often written by people trying to show how smart they are so they write stuff in an extremely generic technical way using no examples and lots of unnecessary jargon. I've seen people try to improve things only to be shut down because they view Wikipedia as a reference manual. To pick a random example, imagine trying to understand matrix multiplicat…
But they aren't all like that, wikipedia varies in quality greatly.
One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…
On the topic of low-level tips: IMO it helps to always try to read one's writing as if speaking it out loud. If the text doesn't flow well when spoken, then it's not good. Like, long-winded parentheses in the middle of a sentence are not good. Sure, the text won't look like those highbrow publications where you flex your mnemonic palaces just to remember what the sentence was about when it started—but at least actual…
Sometimes an analogy is actually perfect, in that both the system you’re lecturing about, and a system the reader already understands intuitively, have exactly the same underlying abstract domain model, just perhaps using different jargon between them.
For example, sound waves vs. electromagnetic waves. A wave is a wave, and if you understand what waves do, it generalizes to other kinds of waves.
Authors reach for the Big Weird Analogy because they often believe they may have stumbled upon a perfectly generalizing underlying abstraction such as “waves.” They’re usually wrong, but I don’t blame them for trying; perfectly-generalizing underlying abstractions are so useful that it’s good to be on the lookout for them.
Sometimes an analogy isn’t perfect, but is close to perfect; in such cases, it is usually helpful to share it anyway, even if it has “holes”, because readers can often find that thinking “on the level of the analogy” helps them to realize additional non-obvious properties of the system they’re learning about. (In the author’s event-streaming analogy: realizing that there are such things as dams on rivers, can make you curious as to whether there’s such a thing as flow-control in message queues. Well, there is!)
One tip I picked up a while back is to be aware of the number of `it`s and other pronouns used. I realized that when my explanation were getting lengthy, I was tempted to avoid duplication by referring to previously mentioned nouns as `it`s, `they`s etc. This practice led to some very confusing sentences, where each `it` meant a different thing. My explanations got noticeably clearer once I started replacing the pron…
Yeah, I work with an English second language guy who uses pronouns excessively, leaving me clueless. In his case I expect he's saving processing power for translating the bigger ideas.
One feature of language that helps with this is gendered nouns. In English "a book lies on a table, destroy it" can mean 2 things. In some languages you use "her" or "him" or "it" depending on the grammatical gender of the noun even if it's not a person. If the table happens to be male and book - female - it's clear what you meant.
pattern 9: starting out abstract That's the most important one for me. I've always thought it was the difference between a good and bad teacher. If you don't start with concrete examples then the listener has no where to map the abstraction. If you start with a couple of examples the listener will start to abstract by themselves. Experts forget that they themselves started with examples.
Curiously, I find this isn't necessarily true for me. I often prefer hearing an abstract explanation first and I have no problem with keeping several abstract terms and relationships between them in mind without having anything "real" to map them to.
Which is another example of "know your audience". Of course, even with the more advanced person I still have a preference to start with the concrete. I'll just move through it more quickly (easier in person, where you can read your audience, Zoom classes with muted participants have been an awful experience for me).
My long-standing annoyance with software documentation is when people don't see that tutorials and reference are different things. They may have tutorials as the only documentation available ( ahem Ansible cough ), or reference as the only documentation. But in fact, the use-cases for those two are different, so effectively they have different audiences. I don't want to learn a language from a dictionary, and I don't…
This [0] helpful resource distinguishes between tutorials, reference material, how-to guides, and explanations. [0] https://documentation.divio.com