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.
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.
Github’s dev assistant thing tries to fill in the code based on what you’ve written, by regurgitating prior knowledge almost blindly — but as a human I can process that regurgitation, and maybe extract a relevant subset of it for my actual use.
I’ve recently realized I do the exact same thing with speech — I’ll talk without thinking, forming sentences out of heuristic systems, and process them after the fact. Then tune the sentence slightly, and continue.
In this fashion, I produce sentences without really knowing what I’ve said, until I think about it later. In much the same way that I drive long distances on auto-pilot, and can’t even remember anything of the route by the end of it.
And those sentences often have ideas that I’ve never actually put together intentionally, but I completely agree with, and upon review, are correct to the best of my knowledge.
I don’t know what speech is, but it’s definitely more than vocalization of my thoughts.
> 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.
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!
Thanks so much, I didn't know there was a term for that! And it was hilarious reading about the UK's use of "popular orange vegetable" to refer to "carrots", a great example of taking this technique to the extreme.
Fortunately, I don't think it's as bad to do that in fiction, because the author is going to establish how the world works to begin with, and therefore makes sure you have enough to know whether the alternate phrases mean that character or someone else, so, at worst, it's just cringey rather than confusing.
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'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".
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..."
I love that you pointed this out (oops, this = the tendency to unclearly define or refer to pronouns). One of the questions I ask the most in trying to clarify what someone said is "what do you mean by 'it'?"
I find this happens a lot also with personal pronouns: you, we, she/he/they, etc. A buddy got angry once and said to me "Why do you always do that?!" And I was really confused. I said, "I'm really confused, why do I always do what?" And he said "ohhh, I didn't mean you, I actually meant me and how I always forget to do things."
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.
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.
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
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.
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.
Even in CS papers, I've seen many clunky explanations that would benefit from introducing notation.
I think authors are sometimes reluctant to use a mathematical style when there's no theorem in the paper. They shouldn't be. Mathematical exposition can be useful for describing experiments and results too.
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.
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.
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.
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!"
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.
I can recommend Andrew Trask’s tutorials and even his book on this. The (e-)book doesn’t go too in-depth with more complex NN applications, but you start out implementing your own NN from scratch using only numpy, which I thought was helpful to get into the topic.
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.
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.
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.
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.
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.
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.
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.)
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.
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".
> 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.
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.
Oh wow, I literally have a blog post queued up about how different kinds of "documentation" can be split into similar categories. Great to see that someone else has had a similar insight!
My categories are Source (Reference), Procedures (~Tutorials), Examples (How-tos) and Meta (Tribal Knowledge, history, etc).
In the context of software teams (and others I'm sure) my anecdotal insight is that without a balance of these kinds of information, certain team functions break down:
- No Source/Reference, no shared deep understanding
- No Procedures, difficulty scaling processes (and difficulty onboarding new team members)
- No examples, harder to develop new skills / level up existing skills
- No meta, no context or "why", leading to less motivation
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’.
The 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.
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.
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.
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”
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!
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).
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/
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
> 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.
"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.
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.
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.
"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).
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.
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.
> 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.
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 :)
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.
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?
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.
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..
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.
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!
She 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?”
>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.
> 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.
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.
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.
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
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.