10 ms·
Patterns in Confusing Explanations
- SaraPolson 5y agohere is one useful article - https://computools.com/business-applications-of-cloud-computing/ https://computools.com/business-applications-of-cloud-comput... I advise you to read
- beprogrammed 5y agopattern 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 5y ago>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.
- carrolldunham 5y agoI dunno... they each seem pretty self-evident.
- n3k5 5y agoThey 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 5y agoIts 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 5y agoThe article also has that list at the start, so duplicating it here in the comments is just noise.
- beprogrammed 5y agoI 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 5y ago> 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 5y agoSometimes 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 5y ago> 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.
- heavenlyblue 5y agoI 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.
- korijn 5y agoI wish this wasn't written just for programmers, so I could share it with more people.
- cbhl 5y agoUnderstanding 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.
- deleted 5y ago[deleted]
- throwaway81523 5y agoDecent post but we just saw this yesterday. https://news.ycombinator.com/item?id=28246519 https://news.ycombinator.com/item?id=28246519
- deleted 5y ago[deleted]
- detaro 5y agotwo 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 https://news.ycombinator.com/newsfaq.html
- throwaway81523 5y agoOh that's interesting, thanks.
- SilasX 5y agoApparently there was still another recent post, where I did put a fairly substantive comment in reply: https://news.ycombinator.com/item?id=28238186 https://news.ycombinator.com/item?id=28238186
- elboru 5y agoAnother 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.
- ChrisKnott 5y agoI 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.
- touisteur 5y agoYou'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 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.
- doorhammer 5y ago"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.
- tomxor 5y ago> 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 5y agoWikipedia 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.
- darkerside 5y agoAm 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.
- Gene_Parmesan 5y agoPersonally, 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.
- darkerside 5y agoInteresting. 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.
- devnull3 5y agoWhat a nice write-up! The points mentioned are applied to the article which talks about those points!
- discreteevent 5y agopattern 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 5y agoCuriously, 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 5y agoIt'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).
- amirGi 5y agoMy 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 5y agoYes! 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 5y agoI 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 5y agoI 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/ https://www.benkuhn.net/thinkrealhard/
- ur-whale 5y agoSure, 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.
- lmilcin 5y agoI 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).
- deleted 5y ago[deleted]
- sliu66 5y agoI think many of the points in the article apply to academic papers as well!
- ur-whale 5y agoIndeed, that's actually the first thing that popped in my mind when I read the title.
- avodonosov 5y agoOne 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 5y agohttps://shoppe24.ph/products/oreo-ice-cream-tub-450ml 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 5y agohttps://en.wikipedia.org/wiki/Mixin#History https://en.wikipedia.org/wiki/Mixin#History
- satisfice 5y agoI 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!
- Gary21 5y agohere is one useful article - https://computools.com/business-applications-of-cloud-computing/ https://computools.com/business-applications-of-cloud-comput... I advise you to read
- NateEag 5y agoRight 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.
- satisfice 5y agoShe is definitely insightful and helpful. But all that fun-ctuation gets manic. I wonder “is she okay? do kidnappers have her family tied up in the basement?”
- qwertox 5y agoOne 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 5y agoOn 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?
- tetha 5y agoVery 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.
- jujodi 5y agoThe 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 5y agoYes 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!
- jujodi 5y agoMy 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.
- wasyl 5y agoOne 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.
- Niksko 5y agoNot 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 5y agoReducing this cognitive load also helps _me_ follow the explanation as I go!
- TravisLS 5y agoThis (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.
- z3t4 5y agoIt 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.
- moonchild 5y ago
- crispyambulance 5y agoThe 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.
- IshKebab 5y agoYeah 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. :-)
- NateEag 5y agoThat 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 5y agoStackoverflow 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.
- deleted 5y ago[deleted]
- jasode 5y agoA lot of this is caused by The Curse of Knowledge: https://en.wikipedia.org/wiki/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.
- sidlls 5y agoSometimes people are just arrogant and want to make sure their audience really knows they (the speaker/writer) really know more.
- kareemm 5y agoOne 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__ 5y agoEven 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.
- aasasd 5y agoMy 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.
- k__ 5y agoI 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.
- xtiansimon 5y agoSwagger ‘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’.
- nonameiguess 5y agoThe number one thing killing me about auto-generated API documentation is when an API takes a "string" that is really an enum and the generated documentation doesn't list out the enum values. Your only recourse is to read the code if it's open source and available in some obvious place, or hope there's a GUI alternative to the API with a pick list, select every option on the list, and intercept the internal API call it makes to get the string representation of each allowed value. Looking at you, Nexus Repository Manager.
- ldarcyftw 5y agoGraphQL tooling exposes enums as such, I believe
- k__ 5y agoI 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 5y ago"All the time", got any examples?
- k__ 5y agoJust 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.
- chefandy 5y agoI'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.
- ihaveajob 5y agoIt's a great list, but I couldn't help chuckle at item 12 being an example of item 11 :).
- Gary21 5y agohere is one useful article - https://computools.com/business-applications-of-cloud-computing/ https://computools.com/business-applications-of-cloud-comput... I advise you to read
- mat0 5y agoJulia Evans is awesome. I would wholeheartedly suggest that you buy some of her zines if you can
- innomatics 5y agoShould 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.
- MagicWishMonkey 5y agoThe person who wrote this is my spirit animal.
- dgellow 5y agoOften 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.
- durbatuluk 5y ago"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).
- SiempreViernes 5y agoIn 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 5y agoExactly. 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.
- Ensorceled 5y agoFrom 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.
- Veuxdo 5y agoI 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.
- kaycebasques 5y agoMeta 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.
- eitland 5y agoMy 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 :-)
- derefr 5y ago> 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!)
- chestervonwinch 5y ago> 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.
- rammy1234 5y agosimple 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 :)
- nemetroid 5y ago> 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.
- shughes 5y agoPattern 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.