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.
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.
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!
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.
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.
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.
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.
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!"
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.
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.
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!
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.
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.
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.
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.
Not just why but also what. So many tutorials miss starting with a high level conceptual overview, and instead just spew out a long list of step-by-step commands to run without even explaining the effects that happen by each command. Or use some variation of pattern 1 from TFA, by only explaining it briefly using new and confusing terminology, like "to frobnicate the fluxiator we need to run 'flux --frob --now' "
I believe this is the main reason so many people struggle learning git, to use it effectively you need to understand the underlying data model, but instead people treat and teach it as a sequence of black-box commands. Once treading out of the happy-flow without understanding what, this sequence will not help you.
Fred Brooks famous quote also comes to mind: "Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious."
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".
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.
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’.
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.
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.
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.
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.
> 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.
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.
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?
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.
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. :-)
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.
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”
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).
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.
> 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!)
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 :-)
That's the most important one for me. I've always thought it was the difference between a good and bad teacher. If you don't start with concrete examples then the listener has no where to map the abstraction. If you start with a couple of examples the listener will start to abstract by themselves.
Experts forget that they themselves started with examples.
Curiously, I find this isn't necessarily true for me. I often prefer hearing an abstract explanation first and I have no problem with keeping several abstract terms and relationships between them in mind without having anything "real" to map them to.
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.
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.
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"
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.
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.
> 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.
[+] [-] wasyl|4 years ago|reply
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.
[+] [-] aasasd|4 years ago|reply
For those who don't normally ‘subvocalize’ in their mind when reading, I guess actual reading aloud to themselves is an option.
[+] [-] SilasX|4 years ago|reply
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!
[+] [-] Niksko|4 years ago|reply
[+] [-] gnuvince|4 years ago|reply
[+] [-] jasode|4 years ago|reply
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.
[+] [-] pessimizer|4 years ago|reply
[+] [-] PoignardAzur|4 years ago|reply
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!"
[+] [-] kareemm|4 years ago|reply
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.
[+] [-] sidlls|4 years ago|reply
[+] [-] kmstout|4 years ago|reply
Wait, so a burrito is just a monoid in the category of endofunctors?
[+] [-] elboru|4 years ago|reply
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.
[+] [-] danybittel|4 years ago|reply
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.
[+] [-] mrspeaker|4 years ago|reply
My favorite articles are where they only explain the "why" and largely leave the "how" as an exercise for the reader!
[+] [-] touisteur|4 years ago|reply
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.
[+] [-] ChrisKnott|4 years ago|reply
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|4 years ago|reply
[+] [-] Too|4 years ago|reply
I believe this is the main reason so many people struggle learning git, to use it effectively you need to understand the underlying data model, but instead people treat and teach it as a sequence of black-box commands. Once treading out of the happy-flow without understanding what, this sequence will not help you.
Fred Brooks famous quote also comes to mind: "Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious."
[+] [-] bsenftner|4 years ago|reply
[+] [-] aasasd|4 years ago|reply
[+] [-] dmlorenzetti|4 years ago|reply
[0] https://documentation.divio.com
[+] [-] xtiansimon|4 years ago|reply
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’.
[+] [-] mapgrep|4 years ago|reply
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|4 years ago|reply
[+] [-] k__|4 years ago|reply
But generally you're right, guides/tutorials for the main use-cases speed up things drastically.
[+] [-] chefandy|4 years ago|reply
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|4 years ago|reply
[+] [-] tomxor|4 years ago|reply
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|4 years ago|reply
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.
[+] [-] avodonosov|4 years ago|reply
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|4 years ago|reply
You were saying?
I can confirm it doesn't work. But for me Oreo barely works as a cookie.
[+] [-] crispyambulance|4 years ago|reply
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|4 years ago|reply
[+] [-] NateEag|4 years ago|reply
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.
[+] [-] amirGi|4 years ago|reply
[+] [-] lmilcin|4 years ago|reply
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).
[+] [-] shughes|4 years ago|reply
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.
[+] [-] derefr|4 years ago|reply
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!)
[+] [-] eitland|4 years ago|reply
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 :-)
[+] [-] discreteevent|4 years ago|reply
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|4 years ago|reply
[+] [-] darkerside|4 years ago|reply
[+] [-] Gene_Parmesan|4 years ago|reply
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.
[+] [-] thow-58d4e8b|4 years ago|reply
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"
[+] [-] k__|4 years ago|reply
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|4 years ago|reply
[+] [-] tetha|4 years ago|reply
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.
[+] [-] nemetroid|4 years ago|reply
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.
[+] [-] devnull3|4 years ago|reply
[+] [-] Veuxdo|4 years ago|reply