[HN Gopher] Patterns in Confusing Explanations
___________________________________________________________________
Patterns in Confusing Explanations
Author : pabs3
Score : 474 points
Date : 2021-08-21 06:05 UTC (16 hours ago)
(HTM) web link (jvns.ca)
(TXT) w3m dump (jvns.ca)
| jasode wrote:
| A lot of this is caused by _The Curse of Knowledge_ :
| https://en.wikipedia.org/wiki/Curse_of_knowledge
|
| That cognitive blind spot causes people to unwittingly write
| confusing explanations in all domains of life.
|
| It's frequently ironic when somebody writes a sentence following
| the rhetorical template: _" Not really sure what the confusion is
| with <X>. It's really simple. [blah blah blah...] And that's
| it."_
|
| Whether it's attempting to explain "monads are like a burrito",
| or neural networks, Git, or how Federal Reserve works, people
| unintentionally write circular definitions.
|
| E.g. _" Not sure what the issue is... Git is just a DAG directed-
| acyclic-graph."_ <-- yes, in the mind of the author, that
| explanation is 100% self-explanatory!
|
| The only way to avoid the issue is to test your tutorials and
| explanations on a variety of readers.
| kareemm wrote:
| One tactic I use to avoid this is to ask myself "would a smart
| person who knows only what I've written up to this point about
| this subject understand what I just wrote?"
|
| If the answer is no, I need to break the concepts down more.
|
| I picture this as a tiny editor sitting on my shoulder who asks
| this question as I write.
| tharkun__ wrote:
| Even that has problems. You might get into too much detail
| very fast.
|
| Take the above examples on explaining something about git. It
| will depend immensely on what you need to explain and what
| you don't need to explain on what the context is and what you
| can assume is already known or not. This can work well enough
| if you have something self contained to document and you are
| the one documenting the whole thing. It falls apart quickly
| as things get larger and as more people work on it.
|
| Pre-requisite reading that you assumed the reader went
| through before and "knows" are moved or slightly re-written.
| There are multiple paths to get to the part of the docs
| you're writing, some of which don't explain everything.
| Readers skip ahead because the pre-reqs are boring or over
| explaining some details they don't need or already know but
| that makes them miss the one important thing that they didn't
| know but is required for your part. If you re-explain it,
| your part might become this boring, skip-ahead part of the
| docs.
|
| There are obviously techniques that can help with this, such
| as pointing towards pre-requisite documentation on a
| particular topic in case someone doesn't know already etc.
| Basically doing what you said, in a structured way with
| hyperlinks. In my experience, most documentation writers
| don't know how to do this properly/don't know the subject
| well enough and most developers that would know enough of the
| nitty gritty don't want to write documentation in the first
| place. There are just some very few (like you I presume) that
| are both good at this and like it. And many places won't let
| you do a good job of it, because you're supposed to be
| coding, not writing documentation for days.
| PoignardAzur wrote:
| Man, the bit about neural networks hits close to home.
|
| I'd kill for a NN tutorial that doesn't go "Anyway, as you can
| see, by multiplying the derivative by a small value we can
| eventually find the local minima of this curve. Anyway, just
| use these exact tensorflow functions with the parameters we
| give you and you're all set!"
| josalhor wrote:
| Have you seen 3Blue1Brown video about it?
|
| https://www.youtube.com/watch?v=aircAruvnKk
| PoignardAzur wrote:
| Yeah, I watched the series a few years ago, and it's still
| an example of the same problem.
|
| The videos give you a good _vibe_ for what a NN network
| does, but they still stop at "if you can get the gradients
| using math wizardry, then you can train your network and do
| tons of cool stuff!"
|
| Meanwhile, if I had to write a neural network trainer from
| the ground up (even a very slow CPU one), I have no idea
| how I'd do it.
|
| Like, I get it! A neural network is a bunch of
| vector<float>! You change the weights in a way that is
| similar to finding the low point of a slope! Yes, every
| damn ML video uses the same metaphors! My question is, how
| do I actually change the values of the goddamn floats?!
|
| I dunno. Maybe I need to watch the videos again and
| something will click.
|
| EDIT: Okay, so the last video in that series is way closer
| to what I was looking for.
| pessimizer wrote:
| I try to fight this by defining any technical term immediately
| before or after the first time I use it. It makes you aware of
| stack depth if you find yourself defining a term within the
| definition of a term within the definition of a term, and may
| give you a hint you should reconsider the order of your
| explanation. It also helps you stay aware of your target
| audience if you stay aware of the words and phrases they're not
| expected to know your usage of.
| bsenftner wrote:
| And in this day and age, we often provide the documentation
| as some type of digital document, and that can have "tool
| tips" for technical terms. Most word processors (Office Word,
| InDesign, LibreOffice) have some type of scripting
| capability, and that's a great way to make sure definition
| tool tips are on every usage of one's technical terms.
| kmstout wrote:
| > "monads are like a burrito"
|
| Wait, so a burrito is just a monoid in the category of
| endofunctors?
| sidlls wrote:
| Sometimes people are just arrogant and want to make sure their
| audience really knows they (the speaker/writer) really know
| more.
| mat0 wrote:
| Julia Evans is awesome. I would wholeheartedly suggest that you
| buy some of her zines if you can
| throwaway81523 wrote:
| Decent post but we just saw this yesterday.
|
| https://news.ycombinator.com/item?id=28246519
| [deleted]
| detaro wrote:
| 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
| throwaway81523 wrote:
| Oh that's interesting, thanks.
| SilasX wrote:
| Apparently there was still _another_ recent post, where I
| _did_ put a fairly substantive comment in reply:
|
| https://news.ycombinator.com/item?id=28238186
| innomatics wrote:
| Should these be anti-patterns? Perhaps calling something an anti-
| pattern is also a confusing way to explain things, or maybe that
| term has gone out of style now.
| eitland wrote:
| My favourite: back in 2005 when I finished my Bachelors degree I
| did some work setting up web payments for a local web shop.
|
| I followed the instructions exactly, used every trick I had
| learned and then some but got stuck several days somewhere around
| page 20 in the documentation on how to compile the module for
| Apache, something just didn't work but there was always just more
| thing I could try, and I assumed the fault was mine since I was
| just a student.
|
| One day I just gave up and mindlessly continued reading.
|
| Around page 100 there was a line something like:
|
| "This is how we used to do it, these days, just download this
| file, put it on this folder and use it like this: "
|
| Worked immediately.
|
| Now, I knew already back then that one should always read through
| the instructions before starting, but I usually think that means
| one chapter at a time, not the whole book :-)
| chestervonwinch wrote:
| > pattern 4: fun illustrations on dry explanations
|
| Or an arbitrary unsplash landscape photo with a tenuously related
| caption. Why do people do this? Is it to stretch the content, or
| just a fad? Surely there's a different way to break up long text
| than adding visual noise.
| qwertox wrote:
| One of the major issues I have with new topics in computing is
| the amount of acronyms and the words and meaning behind them you
| get bombarded with. And you need to understand each one of them
| in order to understand the explanation you're dealing with.
|
| Each acronym opens up a world full of new questions.
| mirekrusin wrote:
| On the other hand one can't expect every single blog post, ie.
| on web service caching or whatever to spend first 50 pages on
| explaining TCP/IP, DNS, TLS, HTTP, WS protocol upgrade, JSON,
| JWT and what not.
|
| If one finds too many unknown acronyms flying around and giving
| headache, it's probably a sign they should step back and sort
| out fundamentals in their head first?
| elboru wrote:
| Another pattern I usually encounter is explaining the how but not
| the why.
|
| Trying to understand how a complex mechanism works is hard, but
| it's harder if you don't know why the mechanism exists in the
| first place.
|
| It would be madness to start studying how an airplane engine
| works without knowing it is used to impulse a flying machine.
| bsenftner wrote:
| If we start asking "why" a huge proportion of many programmer's
| favorite tools would be thrown away - so asking "why" is an
| unexpected minefield in some circles. It forces an evaluation
| the "technical lead" (that set up the habit of these tools) and
| that is far too touchy for many "leads".
| abeyer wrote:
| > asking "why" is an unexpected minefield in some circles
|
| I suspect this largely stems from too many cases of not
| asking "Why do we X?" but rather "Why do we X instead of
| silver bullet/fad of the week Y that will fix all our
| problems?" Many of those technical leads have spent years
| fending off an onslaught of "obviously better"
| tools/processes/etc... that even if they _were_ actually an
| improvement would have grown to consume all available time in
| switching costs alone.
| mrspeaker wrote:
| Whenever I see a "how-but-not-why" article I assume that the
| author doesn't understand the "why" part yet... they've likely
| just rote-learned the "how" part and are regurgitating it.
|
| My favorite articles are where they _only_ explain the "why"
| and largely leave the "how" as an exercise for the reader!
| ChrisKnott wrote:
| I particularly appreciate when very mature projects still
| reference the simple old 1.0 way, and why they had to change it
| to the current mountain of _" ContentStore implements
| AddressableDevice"_ crap. I'm just trying to get Hello World up
| and running why can't I just pass a folder as string? Oh...
| This was brought it to support high availability remote data
| storage...
|
| The experience of starting with something like Lucene at v8.0
| is very different from someone who started when it was simpler
| and probably has both knowledge of and need for any new
| complications.
| hinkley wrote:
| I keep trying to drill into people the fact that with so many
| people on a project, and so much jargon flying around, often
| people are going to be scanning docs looking for the right doc.
| You need an executive summary at the top of each page that
| basically sums up _why_ someone would care to read this page,
| because odds are fairly good that they _don 't_ and if you beat
| around the bush then that feeling of being tricked into wasting
| time can result in some bad feelings about you or the project.
| touisteur wrote:
| You'd enjoy Richard de Crespigny book, QF72, about the A380 in-
| flight engine explosion incident.
|
| One of the clearest reasons he could save the aircraft, is that
| he spent some time in France, meeting w/ the designers of the
| different subsystems, and asked (and was answered clearly) tons
| of 'why' questions.
|
| Yeah yeah 'how' is interesting but in the end, the 'why' is far
| more important, but also rememberable, and it helps when the
| thing is broken or half broken and you have to operate it. And
| I mean the original 'why', not the post-hoc rationalization!
| 'oh yeah the special "attack-beak" on each wing is there to
| give more portance during the landing phase, now that it is in
| "secured mode" (blocked) I will miss % portance during my
| approach I need to adjust'. And it is secured in case of
| hydraulic failure or WTF to avoid triggering spuriously during
| high altitude flight, etc.
|
| I was lucky some time ago to have him comment on a twitter
| thread about automation and human-aircraft interactions, when I
| talked about 'why's:
| https://twitter.com/RichardDeCrep/status/1358560210927771649
|
| Record the whys, that's what jira, code comments, design and
| justification documents are for! Forget the myriad uml, merise,
| whatever young people use these days, give me 'why's !
|
| I highly recommend that book and anything from de Crespigny.
| nbernard wrote:
| For others looking into this book, it seems it is titled
| QF32, not QF72 (QF72 is linked to a different
| incident/pilot).
| touisteur wrote:
| Every time I mess them up. Thanks.
| danybittel wrote:
| I love, "Learning by invention".
|
| Basically, you start with a problem, than the teacher "helps"
| to come up with a solution, (by hints / guides), which casually
| ends up at the solution implemented. I think it's one of the
| reasons people love to reinvent the wheel. When they invent
| something themselves they truly know it inside out. You can
| somewhat do it yourself, if say, you want to learn a new
| library, by first trying to implement the problem yourself,
| then take hints from the library and finally use the library.
| mynameismon wrote:
| Learning by invention is also my favourite way to learn.
|
| However, I find it rather unappreciated among both teachers
| and textbook writers. What is usually done is the result is
| presented on a silver platter to regurgitate and reproduce,
| and important details are glossed over in favour of
| 'simplicity', creating a (dangerous) knowledge gap.
| AussieWog93 wrote:
| First thing I thought of when you said that:
| https://www.youtube.com/watch?v=yYAw79386WI
|
| Done properly, it's an amazingly powerful way of explaining
| things.
| MathMonkeyMan wrote:
| You remind me of something a Physics professor once told
| me.
|
| He said (I'm paraphrasing) "when you get to really learning
| the Physics, it's not an incremental logically consistent
| picture rooted in mathematics like in the textbooks. It's
| mostly a bunch of little tricks that you learn when to
| apply, and sometimes you get somewhere."
|
| He wasn't making a pedagogical point, but I wonder if being
| compelled by the "learn by invention" style is in some way
| detrimental to learning how to solve hard novel problems.
| mynameismon wrote:
| To be fair, 'Learn by invention' can be detrimental if
| one is trying to derive a result which requires
| significant prior knowledge that the learner lacks.
| However, quoting a simple physics example of what I mean:
| One can prove the Work-Energy theorem with simple
| manipulations of the basic definitions of displacement,
| velocity and acceleration without having to learn it like
| a law. One cannot derive Newton's three laws, on the
| contrary.
| lyaa wrote:
| Most of physics is not a great counter-example to
| learning by invention. There are several ways to derive
| Newton's three laws. It's a fun exercise in Lagrangian
| mechanics.
|
| Perhaps quantization or the curvature of space would be
| better examples as they require prior knowledge of
| experimental data (assuming we ignore proposed
| philosophical arguments that stray a bit too far from
| physics imho.)
| zhengyi13 wrote:
| This is _exactly_ how Syntax 1 was taught at UC Santa Cruz
| when I attended.
|
| We started with a general question of "What is the simplest
| sentence you can think of?", and then moved to "How could you
| represent that symbolically? Generically?". With the
| professor's guidance, the solutions and systems of
| representation evolved over the course of the quarter to
| become more rich and complex, and just so happened to trace
| the development of syntactic theory from roughly the 50s to
| the 70s. Then you took Syntax 2 tracing roughly the 70s to
| the 90s, and by the end of that time, you were ready to look
| at modern problems.
| satisfice wrote:
| I like the content! But I find that the use of exclamation points
| detracts from it! Maybe I am biased?! Because, for instance, I
| also avoid emoticons, and for the same reason! Which is: it can
| make the prose seem goofy and patronizing! But just in case you
| need exclamation points in order to hear what I write, I have
| used them in the comment!
| NateEag wrote:
| Right there with you.
|
| I think it's an attempt to make the text 'feel' chipper,
| optimistic, and newbie-friendly.
|
| Julia writes some really good stuff, but that particular quirk
| in her writing has annoyed me for a long time.
| Gary21 wrote:
| here is one useful article - https://computools.com/business-
| applications-of-cloud-comput... I advise you to read
| chefandy wrote:
| I'd add: over-verbosity, or conversely, seeing terseness as a
| goal in itself.
|
| A pet peeve on a smaller order: bad variable/function naming in
| beginner examples.
|
| Hypothetical: You're writing a true beginner tutorial introducing
| the core concept of fooKinetic in your cool new gaming language.
| Many authors choose variable and function names similar to the
| concepts they're introducing, which adds unnecessary cognitive
| load for those who can't yet automatically visually parse the
| language. Someone who's looked at the code even for a couple of
| hours completely understands what `fook | fook ~~ fooKin | fook
| -- Fook{}` means, but to a complete language beginner, it's
| nonsensical. You lost an opportunity to reinforce your basic
| syntax, didn't communicate the core concept of the tutorial, and
| likely turned off people closer to the beginning of their coding
| journey.
| nerdponx wrote:
| I would also offer that whitespace and commenting needs are
| very different in "demo" code versus in "real" code. Even the
| font and syntax highlighting style can make the difference
| between a readable demo snippet and a meaningless blob.
| tetha wrote:
| Very much agree on #1 and #2, and 6/7/8 in the same vein. Our
| internal documentation had a quality jump when we started to
| explicitly prefix documents with their intended audience.
|
| For example, documentation targeted at our customer support
| assumes a basic familiarity with the monitoring systems and the
| structure of the customer facing services. However, documentation
| for the support cannot build on concepts like the network
| architecture, or shell access to servers.
|
| On the other hand, documentation for operations engineers doesn't
| have to slow down the reader with information about the network
| architecture, as that's assumed to be known.
|
| And being somewhat consistent with these documentation personas
| simplifies the onboarding of new employees, because there is a
| known knowledge base you need to access the documentation
| effectively.
| Veuxdo wrote:
| I distinctly recall in CS102 being taught classes with the
| bicycle example. I'm glad I'm not the only one who was confused
| by that.
| rammy1234 wrote:
| simple examples, jargon-free sentences, too many concepts while
| explaining a concept, concept explained without an example,
| unrealistic examples, not explaining why we do something in the
| place and jumping into explaining them.... If there is a
| technical book free of all these anti patterns I am buying it :)
| [deleted]
| MagicWishMonkey wrote:
| The person who wrote this is my spirit animal.
| nemetroid wrote:
| > pattern 4: fun illustrations on dry explanations
|
| The description restates this as _" make the design reflect the
| style of the explanation"_, which I think is better, since it
| goes both ways.
|
| I can't stand cutesy writing on technical topics, but I've
| nothing against cutesy drawings, so I can't agree with the title.
| But on the other hand, I've been disappointed a few times by
| "friendly style" writing hiding in dry visuals, so I guess I
| agree about wanting consistency.
| beprogrammed wrote:
| pattern 1: making outdated assumptions about the audience's
| knowledge
|
| pattern 2: having inconsistent expectations of the reader's
| knowledge
|
| pattern 3: strained analogies
|
| pattern 4: pretty pictures on confusing explanations
|
| pattern 5: unrealistic examples
|
| pattern 6: jargon that doesn't mean anything
|
| pattern 7: missing key information
|
| pattern 8: introducing too many concepts at a time
|
| pattern 9: starting out abstract
|
| pattern 10: unsupported statements
|
| pattern 11: no examples
|
| pattern 12: explaining the "wrong" way to do something without
| saying it's wrong
| null_object wrote:
| >pattern 1: making outdated assumptions about the audience's
| knowledge
|
| >pattern 2: having inconsistent expectations of the reader's
| knowledge
|
| >pattern 3: strained analogies
|
| >pattern 4: pretty pictures on confusing explanations...
|
| edit: I understand you're trying to help, but... Your post
| simply listing the 'titles' of each of the categories is
| ironically itself an _example_ of exactly the problem the blog-
| post is discussing: your bare list implies that these are all
| known rhetorical devices (assuming knowledge) whereas the
| blogger is _attempting to articulate the reasons why_ these
| categories are confusing for the reader /learner.
|
| In other words, the value of the blog-post is in the detail,
| not in some list that can be summarized like this as a tl;dr.
| beprogrammed wrote:
| I have to disagree. And to each is own.
|
| Having read the article I found that list painted a clear
| picture and summed up the patterns nicely.
|
| If one reads that and wants more, read the article.
|
| (Not authors)Pattern 13: Using excessive prose where less
| will do
| kbenson wrote:
| > Pattern 13: Using excessive prose where less will do
|
| That's just a mix of #1 and #2. "Excessive" prose is
| usually people trying to provide nuance through language
| with the assumptions others will be familiar enough with
| that type of language for it to provide benefit. Different
| words have slightly different connotations which can help
| if people understand those differences.
|
| Fundamentally, it's the same problem as using acronyms that
| people aren't comfortable with to immediately parse so they
| don't cause extra mental load.
|
| The alternative is to make everything really simple, but
| the lost nuance can affect communication negatively as
| well, as Randal Munroe's Thousand Word Challenge showed.
| beardyw wrote:
| Sometimes a lengthy explanation is just a lazy stream of
| consciousness.
|
| "I have only made this letter longer because I have not
| had the time to make it shorter." -- Blaise Pascal.
| null_object wrote:
| > I have to disagree. And to each is own. > Having read the
| article I found that list painted a clear picture and
| summed up the patterns nicely.
|
| > (Not authors)Pattern 13: Using excessive prose where less
| will do
|
| Ok I guess we simply have to _assume that people know_ the
| underlying explanations for why _assumed knowledge_ is a
| bad pattern.
| carrolldunham wrote:
| I dunno... they each seem pretty self-evident.
| n3k5 wrote:
| They could be (and even seem) much more self-evident (and
| valuable as a tl;dr) if they were one-sentence summaries
| instead of a copy-paste of a paragraph from the beginning
| of the linked page.
| bawolff wrote:
| Its a tl;dr. If you write 12 sentences its hardly a tl;dr
| summary anymore.
|
| I thought it was a pretty self-evident summary. The
| article is great too and goes in more detail, but i have
| trouble imagining anyone saw that summary post, and was
| like "pattern 11: no examples" - i have no idea what that
| could possibly mean
| detaro wrote:
| The article also has that list at the start, so
| duplicating it here in the comments is just noise.
| heavenlyblue wrote:
| I have a team member at work like you while me being the
| complete opposite. I am not sure I still understand them well
| enough to say whether they are just stupid or it's me. But
| frankly at least once already there was a situation where
| they said that my explanation was too vague and I didn't
| listen and then month later I re-read what I wrote and it was
| indeed vague now :)
|
| So while I disagree a lot with your statement my experience
| told me that actually there's a lot of truth to what you are
| saying.
| jujodi wrote:
| The Wikipedia example is a gem because it explains everything
| that is wrong with Wikipedia. All of "technical" information on
| Wikipedia amounts to nothing concrete or useful unless you're a
| historian..
| quickthrower2 wrote:
| Yes I was thinking about this the other day. You need to be
| such an expert to understand a technical Wikipedia that you
| don't need the article!
| korijn wrote:
| I wish this wasn't written just for programmers, so I could share
| it with more people.
| cbhl wrote:
| Understanding your audience (and your audience's knowledge) was
| one of the first things I learned in public speaking / rhetoric
| class in college... so I suspect more generic examples would
| hurt your ability to persuade folks. But it seems reasonable
| enough to take the core ideas and reframe them against
| different examples that better resonate with the "more people"
| you're thinking of.
| sliu66 wrote:
| I think many of the points in the article apply to academic
| papers as well!
| ur-whale wrote:
| Indeed, that's actually the first thing that popped in my mind
| when I read the title.
| wasyl wrote:
| 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 pronouns with whatever they would refer to instead. Sometimes
| I also add an additional noun ("this practice") to make the
| pronoun clearer.
|
| I still overuse pronouns sometimes, but when I want to be extra
| sure my point gets across, I'm trying to limit them as much as I
| can.
| hobofan wrote:
| This not only applies to "it" but also to other jargon-y words
| that are used a lot in a single discussion. If you find that a
| single word is used disproportionally often in a discussion,
| it's almost always worth it to take a step back and ensure that
| everyone in the discussion has a shared (clear!) understanding
| of what that word means.
| SilasX wrote:
| I've seen newspapers handle this[1] by having other phrases for
| the same referent -- instead of just switching between "the
| pope" and "he", they'll slip in "the Bishop of Rome" or "the
| vicar of St. Peter".
|
| 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!
| 8note wrote:
| The Pope is an interesting example since they represent
| several things, each having separate responsibilites.
|
| It just so happens that the pope has all those roles at same
| time time
| SilasX wrote:
| Yeah but they rarely use those alternate phrases
| specifically to refer to the authority he has in that
| title's capacity.
| Niksko wrote:
| 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.
| wasyl wrote:
| Reducing this cognitive load also helps _me_ follow the
| explanation as I go!
| benibela wrote:
| That is why scientific papers have so much "let x be ..."
| mapgrep wrote:
| Legal documents do this as well (albeit in different
| language, typically at the top of the document).
| atoav wrote:
| You can use variables, this is also done in philosophy where
| a philosopher will first define the precise meaning of a
| certain term they are using and then use it within further
| discussion. This is totally okay if done transparently and
| for a reason.
|
| What is a pitfall however to declare these variables
| implicitly and rely on them too long. As a writer it is very
| easy to forget this because of course you know what topic you
| are writing about. As a reader however you have to do some
| work to get into the same (or similar) world of thinking as
| the one the writer created for you.
|
| Same is true for speaking. Of course I know what I mean when
| I say something, but the other person might not even know
| what language I am speaking in and would have to decipher
| that first. In a similar way people have to decipher abstract
| topics you might be talking about
| TravisLS wrote:
| This (ironically). I often start enforcing a "no pronouns" rule
| for myself and others when conversations and concepts get more
| complicated. It (the rule) is awkward at first but makes a big
| difference in mutual understanding.
| gnuvince wrote:
| That's a good one, especially if using pronouns causes people
| to have to backtrack in their reading. Another pattern that
| personally annoys me is when people use "the former" and "the
| latter"; I'm forced to go back in the text to remember which
| one was mentioned first and which one was mentioned second.
| speeder wrote:
| I get extra annoyed at this because I am not an English
| speaker and never remember what former and latter means.
| secondcoming wrote:
| latter = last, former = first.
| derangedHorse wrote:
| This is one of the most helpful critiques I've ever received in
| my college english classes
| z3t4 wrote:
| 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.
| SilasX wrote:
| That's actually an example of making it more confusing. Did
| the client crash?
|
| 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".
| rdiddly wrote:
| Someone tells you "the server crashed" and that's
| confusing? The list of things that happened after the
| connection attempt is one item: The server crashed. Unless
| you think the writer is actively trying to trick you, I
| think you can probably assume the client's crashing would
| be on the list if it had happened. It's a good convention
| to follow because cataloguing non-events is tedious: "I ate
| breakfast and did not choke and did not have any allergic
| reactions and my house wasn't hit by an airplane and 57
| porcupines didn't try to crawl up my butt and breakfast did
| not consist of filet mignon nor pizza nor cauliflower nor
| rocks..."
| SilasX wrote:
| Oh I thought the "it" version was being presented as less
| confusing.
| LouisSayers wrote:
| Ahh "former" and "latter" - for people that like to use
| these terms, just repeat the damn word.
|
| I find the use of these terms does the reader a disservice
| by giving them additional cognitive load.
|
| You typically end up having to go back and read whatever
| was written again.
| moonchild wrote:
| The practice of substituting pronouns 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.
| behnamoh wrote:
| It's an interesting example to _confuse_ most advanced `AI
| 's. They just don't understand what `it' refers to in the
| first sentence.
| archsurface wrote:
| 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.
| ajuc wrote:
| Pronouns in some languages are less confusing than in others,
| he might be coming from a language where pronoun-heavy
| sentences are clear.
|
| 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.
| frumiousirc wrote:
| I agree that overuse of "it" is very confusing and in both the
| written word and in speech. Overuse of "it" is often a sign
| that the writer or speaker is not fully clear on the topic in
| their own mind.
|
| On the other hand, "under use" of "it" can also lend friction
| to understanding as "under use" of "it" destroys briefness.
| Cognitive load increases as we wade through "under use" of "it"
| again and again.
|
| A little bit of it is good. Too much of it is bad.
| hammock wrote:
| The important bit is not overuse or underuse, it's proper
| use. I was taught in high school rhetoric class:
|
| _all pronouns must have a clear, one-word antecedent._
|
| This principle was drilled into my brain, and it's helpful.
| aasasd wrote:
| 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 people
| may derive utility from the result.
|
| For those who don't normally 'subvocalize' in their mind when
| reading, I guess actual reading aloud to themselves is an
| option.
| bsenftner wrote:
| This is a great practice, echoed by serious writers and
| technical writing guides.
| gypsyharlot wrote:
| Great advice! Thank you.
| behnamoh wrote:
| For a long time I've tried to speed up my reading my turning
| off the `sub-vocalizing' machine in my mind, only to realize
| that sub-vocalizing actually helps understand the meaning of
| technical/math texts better.
|
| On a relevant note: There was a post on HN a while ago which
| basically was about how using language (and probably,
| speaking out loud) is actually a `feature' or `technology' of
| human mind. For long, we have been mocked for speaking our
| thoughts out load, but turns out, it in fact helps organize
| thoughts and get to more logical conclusions, free of the
| `fluid' logic-space of the silent mind. Ironic because
| sometimes I'm fed up with the _load_ rush of thoughts in my
| mind.
| aasasd wrote:
| > _There was a post on HN a while ago which basically was
| about how using language (and probably, speaking out loud)
| is actually a `feature ' or `technology' of human mind_
|
| Really would like to see that post, as I've been vaguely
| interested in this very topic for quite a while. Is there a
| chance that you remember any key words that might've been
| in the title, so I could plug them into the HN search?
|
| From what I gathered so far, one hypothesis is that
| language development went hand-in-hand with both
| consciousness and empathy, i.e. social cognition: as we
| learned to see the world from the viewpoint of others, we
| also expanded the abilities to communicate with others and
| think to ourselves.
| avodonosov wrote:
| One of my favorite bad analogies is mixins. I came up with this
| Mixin FAQ to satirize how mixins are often explained.
|
| _Mixin FAQ_
|
| Q: What is a mixin?
|
| A: Mixin allows to inject functionality into classes. Mixins
| first appeared in the Flawors system and were inspired by an ice
| cream shop offering a basic flavor of ice cream (vanilla,
| chocolate, etc.) with a choice of optional "mix-in" ingredients
| like nuts, cookies, candies, etc.
|
| Q: Can I mix-in a ServerSocket into a ColorPicker?
|
| A: Yes, why not.
|
| Q: How will it work?
|
| A: Like ice cream with cookies.
| scotty79 wrote:
| https://shoppe24.ph/products/oreo-ice-cream-tub-450ml
|
| You were saying?
|
| I can confirm it doesn't work. But for me Oreo barely works as
| a cookie.
| avodonosov wrote:
| https://en.wikipedia.org/wiki/Mixin#History
| darkerside wrote:
| Am I the only one that appreciated strained analogies? They are
| meant to create a visual in the reader's mind so they can
| remember the pieces that are being shared. Of course, if the
| analogy is good, it won't feel strained. But it seems like the
| author is against any extended analogies at all, which I think is
| a mistake.
| thow-58d4e8b wrote:
| Strained analogies are bad enough, but a special award for
| teaching anti-patterns should go to analogies to some local
| features - e.g. to a sport that's popular only in some
| countries, or a local geographic feature or corporation.
|
| To someone reading in Europe, explaining something by analogy
| to baseball innings, bases and pitchers reads: "think of it
| like dipping your youtiao in chashaojiang instead of haoyou"
| Gene_Parmesan wrote:
| Personally, when it comes to technical topics, I have not ever
| found an extended analogy that made a subject less confusing.
| Analogies are fine as a quick way to introduce the flavor of a
| topic -- saying "Kafka is like a river..." at least gets me
| started on the right footing. But when they extend onwards and
| onwards, I always just end up feeling like the analogy-creator
| is sort of reveling in a semi-poetic alignment they have found.
| Such alignments can be very strongly linked in one's head to a
| topic, because that's how brains learn -- they learn by linking
| new things to already-known things. However, they can also be
| quite person-dependent, and rarely do they contain enough hard
| & fast detail to count as helpful in the context of a technical
| explanation.
|
| Someone can write lots of paragraphs on this Kafka/river
| analogy (just one random example), but that doesn't impart in
| my head the same neuronal linkage that they have. Instead I am
| left, like the post author, trying to figure out how far the
| analogy extends, what the limits are (okay, so messages are
| like notes-in-bottles dropped in the river... but what are the
| fish? are there fish?), and so on. I would rather get clear,
| detailed explanation, and then think through the subject on my
| own time in a way that allows my brain to build its own
| relationships with the information. Maybe instead of rivers, my
| brain begins to understand Kafka as, I don't know, highways.
| monocularvision wrote:
| There was recently some explanation of Kafka that was done as
| a children's book about beavers or something. I found it
| utter baffling where most folks seemed to sing its praises.
| darkerside wrote:
| Interesting. I consider myself a "generous audience" in
| general. Quick to laugh, willing to suspend disbelief, eager
| to listen. I wonder if there is a correlation between open-
| mindedness of the listener/reader and the effectiveness of
| extended analogy.
|
| I can see your point, that if you try to "steal" the analogy
| (in the Picassian sense of the word), the analogy could
| become more distracting than helpful. If you take it for what
| it is and try to focus on the author's or speaker's vision,
| they probably work much better.
| ihaveajob wrote:
| It's a great list, but I couldn't help chuckle at item 12 being
| an example of item 11 :).
| devnull3 wrote:
| What a nice write-up! The points mentioned are applied to the
| article which talks about those points!
| aasasd wrote:
| 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 want to
| wade through the tutorials when looking for one particular
| concept.
| mapgrep wrote:
| In open source the trend unfortunately seems to be toward a
| Readme.md with a couple of simplistic examples, then you're
| left to read the source in lieu of a proper API reference.
|
| I still remember CPAN perldocs as a high water mark for docs.
| They had specific sections for examples, starting with the
| summary at the top, and another for proper reference. And more
| importantly a strong culture of good docs. The examples tended
| to be close to comprehensive, progressing from simple to
| complicated problems. Then there would be a rundown of
| arguments and return values for the key methods.
| 3pt14159 wrote:
| My biggest annoyance with software documentation is when it
| _only_ has simple examples and doesn 't mention obvious corner
| cases or covers the case where there is one related object but
| doesn't cover the case where there are multiple objects.
| xtiansimon wrote:
| Swagger 'documentation'.
|
| I understand every programmer I talk to loves this auto
| generated 'documentation' (prolly for selfish reasons). For me
| the tautological definitions, and lack of overview (which
| resources you need to form basic reporting--my introduction was
| swagger api for a Platform POS) undermine the description as
| 'documentation'. I'm not complaining about what Swagger does,
| but about the cavalier way other programmers and vendor
| managers sound all chipper about their (un-)helpful
| 'documentation'.
| dmlorenzetti wrote:
| This [0] helpful resource distinguishes between tutorials,
| reference material, how-to guides, and explanations.
|
| [0] https://documentation.divio.com
| solarmist wrote:
| Yup! This helped me immensely when I started writing
| documentation more regularly. In the past I used to mix all 4
| and ended up confusing everyone.
| aasasd wrote:
| Indeed, that was the first time I've seen someone clearly
| voice more-or-less the same view, when the link previously
| appeared here on HN.
| k__ wrote:
| I think, reference only can work when it's really really good.
|
| But generally you're right, guides/tutorials for the main use-
| cases speed up things drastically.
| dgellow wrote:
| Often it's not the explanation in itself that is confusing. It
| just takes some thinking and learning the terminology and jargon
| to develop a good understanding of a concept.
|
| Information => confusion => more research => reformulate with
| your own words => finally reached a good grasp of the topic
|
| That's a very common way to learn about something and doesn't
| have a lot to do with the quality of the initial information. You
| have to go through the process of being confused, then build your
| mental model of the thing.
| Gary21 wrote:
| here is one useful article - https://computools.com/business-
| applications-of-cloud-comput... I advise you to read
| crispyambulance wrote:
| The patterns Julia gives absolutely distill the bad practices
| when well-intentioned people try but fail to explain something.
|
| In particular, you can see examples of "inconsistent expectations
| of reader knowledge" and "starting out abstract" ALL THE TIME in
| stackoverflow. Someone will ask a specific question about a
| problem they're having but then have their question closed as
| dupe and referred to another related (or not) question that has
| somebody's idea of a "canonical" answer. That answer is often
| highly comprehensive but it is also often a poor fit answer for
| someone that is just trying to figure something out and is not
| equipped to handle and apply an abstract generalized solution to
| their specific problem.
| NateEag wrote:
| That does happen, but the StackOverflow people aren't wrong.
|
| If there's a good, general answer to the question, then it's on
| the asker to expand their knowledge as they need to in order to
| understand that general answer.
| crispyambulance wrote:
| Stackoverflow people are frequently and abundantly "wrong" as
| far as emotional intelligence and empathy goes.
|
| Sometimes a simple question needs a simple answer and not
| treatise or "canonical" answer.
| IshKebab wrote:
| Yeah I guess that's because StackOverflow itself doesn't know
| what it wants to be. Is it a Q&A site? A reference manual? A
| programming wiki? Who knows, but I guess we'll close your
| question just to be safe. :-)
| discreteevent wrote:
| 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.
| feanaro wrote:
| 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.
| Jtsummers wrote:
| It's definitely an individual preference, but it also relates
| (IME) to the base knowledge the person has of the domain. If
| I want to explain a novel programming concept to a colleague
| and they've been programming for 20 years and understand
| multiple language paradigms I can often start out very
| abstract. They'll fill in the concrete use or example
| themselves. On the other hand, with a new hire or a non-CS
| major (I've worked with a lot of EEs who worked as
| programmers but weren't _trained_ as programmers) a concrete
| example which is then generalized or made more abstract works
| better.
|
| 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).
| [deleted]
| doorhammer wrote:
| "test your explanations! ...running an explanation by a few
| people who don't already know the concept helps to catch
| incorrect assumptions I've made."
|
| I love this.
|
| As I get more skilled with a thing I think I can have more
| confidence that I'm doing it well and according to best practices
| up front but that my highest level of confidence comes from
| employing the thing in practice and observing the results.
|
| That could be deploying code to prod with monitoring, having
| another dev review my code to see if it's readable, having users
| interact with my system while I observe, or in this case seeing
| if someone can read my explanations and understand the ideas I'm
| trying to communicate.
| k__ wrote:
| I write technical explanations for a living and are often baffled
| how bad some people write.
|
| I don't even mean non-native speakers, but people from the UK/US.
|
| People tend to leave out crucial information all the time and
| can't focus on what they try to explain. As if they don't read
| their texts after they've written them.
| C19is20 wrote:
| "All the time", got any examples?
| k__ wrote:
| Just yesterday I read some guides to instrument my IaC with a
| monitoring service. Their lib requires to call a flush
| function, but this wasn't mentioned in the guides.
|
| Somewhere at the end of the API ref, after a list of
| deprecations, they mentioned the flush function.
|
| Wouldn't have expected such important info buried that deep.
| tomxor wrote:
| > 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 nail it, then for
| others they are difficult to explain and it may not even be clear
| to the author how they came to understand it in relation to the
| primary subject - which is when they tend to drop the ball and do
| some hand waving.
|
| Multidisciplinary subjects probably make it harder still, since
| there is relevant knowledge that the target audience may or may
| not know due to their different backgrounds.
| IshKebab wrote:
| 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
| multiplication from this:
|
| > In mathematics, particularly in linear algebra, matrix
| multiplication is a binary operation that produces a matrix
| from two matrices. For matrix multiplication, the number of
| columns in the first matrix must be equal to the number of rows
| in the second matrix. The resulting matrix, known as the matrix
| product, has the number of rows of the first and the number of
| columns of the second matrix. The product of matrices A and B
| is denoted as AB.
|
| Binary operation? Why is it talking about details like column
| numbers before it even explains what matrix multiplication is
| _for_?
|
| It should be more like this:
|
| > Matrices are 2D grid or arrays of numbers that can represent
| an operation on a vector. For example scaling or rotating it
| (or both). Two matrices can be multiplies together to form a
| new matrix that represents a combination of the operations of
| the input matrices. For example if A is a matrix that doubles
| the scale of a vector and B is a matrix that rotates it by
| 90deg, then the product AB will be a single matrix that both
| rotates and then scales the vector.
|
| > The matrix product is calculated by summing the dot product
| of corresponding rows and columns of the inputs as shown in
| this illustration
|
| And then jump straight to the Illustration section which is
| easily the most understandable part of the article.
|
| But that edit would probably be reverted because some pedant
| will point out that matrices aren't _only_ used for
| manipulating geometric vectors or whatever.
| tomxor wrote:
| Oh yeah, a lot of wikipedia intros are what I like to call
| "code golfing" in human language, someone attempting to fit a
| comprehensive description in 1 or 2 sentences. Which they
| technically achieve, but it's only intelligible by people who
| already understand it, so it's also pointless.
|
| But they aren't all like that, wikipedia varies in quality
| greatly.
| shughes wrote:
| Pattern 12 was something I learned early (fortunately) in my
| software development journey. I think the article I was reading
| was something to do with how to properly partition your disk (it
| was about 15 years ago, so fuzzy details, but I remember it was a
| topic that directly impacted disk storage). Anyway, it listed a
| series of steps that he followed, which I had printed out and
| began following (again, 15 years ago).
|
| The paragraph following his series of steps then said, "I soon
| realized that this was not what I wanted, and in fact, it made
| for a cleaned out disk. No good. So next.."
|
| And yes, it wiped my disk clean too. The light-hearted way in
| which he wrote this infuriated me. I just wiped clean my computer
| because of his article. Granted, I should not have blindly
| followed the article, and it was a good lesson that has prevented
| me from ever making the same mistake again. But the way he listed
| the steps in a very procedural, "this should be followed" format;
| it felt very deceptive, and the result was irreversible.
| [deleted]
| jujodi wrote:
| My issue with pattern 12 (explaining the wrong way without saying
| it's wrong) isn't that I get confused about what is the right or
| wrong way of doing something, it's that I'll usually spend the
| time to actually develop examples, and if I was told up front
| that I was about to be shown the wrong way I would only read it
| so I didn't have to bother with the refactor during the learning.
| kaycebasques wrote:
| Meta comment: the author is applying the "invert, always invert"
| strategy to technical communication. I've never seen that done
| before. Style guides and quality control checklists are usually
| framed in the affirmative/positive. "Be concise." Etc.
| amirGi wrote:
| My default mindset used to be "I'm not getting this -> I'm
| stupid", and I've been slowly shifting my mindset to "I'm not
| getting this -> this is probably not being explained well"
| mrspeaker wrote:
| Yes! Teaching is really hard, and is an independent skill from
| having knowledge about a subject. Many blog posts and articles
| are written by people who know the domain, but are not good
| teachers.
|
| The same goes for teachers in general - you can have professors
| who are very smart, but are poor teachers. It's a completely
| different skill set... that's why it's so exciting when you
| find someone who has both!
| ur-whale wrote:
| I find that it's usually a combination of both.
|
| What usually convinces me that we're reaching into the "I'm
| just not smart enough" territory is when I listen to multiple
| explanations from multiple sources and I'm still stuck
| (although ... I find that on certain subject people are just
| parroting each other a lot, which makes me often question
| whether the person doing the explaining actually understands
| the topic at all).
| amirGi wrote:
| I think it's usually less of a "I'm not smart enough" and
| more of a "this may take significant time to understand
| well." Topics that are deemed too complex usually just
| require a significant amount of previous knowledge that you
| may not already have, and you just need to spend a lot of
| time thinking and learning about them. More on this here -
| https://www.benkuhn.net/thinkrealhard/
| ur-whale wrote:
| Sure, it's a nice and egalitarian opinion and all but that
| doesn't take into account the situation when the guy next
| to you groks something 10 times faster than you do and can
| move on to the next topic in the blink of an eye.
|
| As an extreme of this, if it takes you 20 years of hard
| study to grok a topic that normal people absorb in 6 months
| ... harsh to say, but you don't fall in the "smart" bucket.
| elondaits wrote:
| Yes! The same with movies (specially with thrillers, capers,
| noir, etc.). I always assumed I wasn't paying enough attention
| and important bits of information flew over my head. As I got
| older and often when rewatching movies, I realized there's a
| lot of hand waving, vague explanations and basically shoddy
| writing, even on big movies.
| derefr wrote:
| > I think authors [reach for Big Weird Analogies] because.. it's
| kind of fun to write these Big Weird Analogies! Like, is there
| something in a stream processing system that's like a dam? Maybe!
| It's kind of fun to think about! But even though these can be fun
| to write, they're not as fun to read - it's a struggle to extract
| the actual technical facts you want to know.
|
| 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!)
| durbatuluk wrote:
| "I think" posts should always handled with care because we have
| no real evidence, just your "I think". Pattern 12 is often used
| to promote critical thinking and to shake previous believes. Most
| teachers want the class to realize something is wrong because
| this type of realization helps the process of learning (knowledge
| coming from you, not them).
| Ensorceled wrote:
| From the article:
|
| > pattern 12: explaining the "wrong" way to do something
| without saying it's wrong
|
| I encounter Pattern 12 in three different ways:
|
| 1. Google for solution problem. Find tutorial. See solution
| that, for all intents and purposes, looks correct. Adapt to my
| problem. Doesn't work. Return to to tutorial. "Surprise! How
| much time did you lose!?!?".
|
| 2. Following tutorial. See solution. Something seems off. Wrack
| my brain trying to reconcile the solution given that it seems
| wrong. Scroll down. "Surprise! That was the incorrect
| solution."
|
| 3. Following tutorial. See solution. Seems legit, integrate
| solution into my learning. "Surprise. Now your brain is broke!"
|
| There is no version of this pattern that I've encountered where
| I didn't both treat the author as an unreliable narrator going
| forward and also assume they were a bit of an ass.
|
| You can't learn if you no longer trust your guide.
| SiempreViernes wrote:
| In the case of 12 the objection is that the author is unfairly
| tricking (intentionally or not) the reader into making a
| mistake, which is unnecessarily hostile.
|
| That's why one of the suggested fixes is simply to place a
| warning that the following is not to be read as reliable
| gospel.
| Ensorceled wrote:
| Exactly. It doesn't even have to necessarily say "this is
| wrong" ... just something that causes you to engage with the
| example as potentially unreliable or not the best solution.
|
| "The traditional way to solve this problem ..."
|
| "Other tutorials suggest something like the following ..."
|
| It's just sadistic to give an example that doesn't work and
| then I waste time looking for a syntax error or typo that
| doesn't exist.
| lmilcin wrote:
| I think confusing explanations are kinda same as your first
| implementations.
|
| If you don't refactor it to clean up your model, it will stay
| confused.
|
| Once I have some explanation, I try to "refactor" that
| explanation by understanding the exact meaning of specific words
| (domain model) of that explanation.
|
| Once I understand exact meanings and relations between all parts
| of the explanation it starts making much more sense because it
| moves from specific (made for me) to general (made for every
| case).
___________________________________________________________________
(page generated 2021-08-21 23:01 UTC)