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.

Sure, I just found the post: https://psyche.co/ideas/talking-out-loud-to-yourself-is-a-te...

Thanks!

This is a great practice, echoed by serious writers and technical writing guides.

Great advice! Thank you.

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!

In fiction writing this pattern known as “Burly Detective” Syndrome, see https://www.sfwa.org/2009/06/18/turkey-city-lexicon-a-primer..., https://tvtropes.org/pmwiki/pmwiki.php/Main/BurlyDetectiveSy...

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.

The Pope is an interesting example since they represent several things, each having separate responsibilites.

It just so happens that the pope has all those roles at same time time

Yeah but they rarely use those alternate phrases specifically to refer to the authority he has in that title’s capacity.

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.

Reducing this cognitive load also helps _me_ follow the explanation as I go!

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.

I get extra annoyed at this because I am not an English speaker and never remember what former and latter means.

latter = last, former = first.

It can also be used to make text easier to understand, for example:

    The client connected to the server, then it crashed

vs

    The client connected to the server, then the server crashed.

The practice of substituting pronouns can also be used to make text easier to understand, for example:

    The client connected to the server, then it crashed

vs

    The client connected to the server, then the server crashed.

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..."

Oh I thought the “it” version was being presented as less confusing.

Ah, no wonder!

Ahh "former" and "latter" - for people that like to use these terms, just repeat the damn word.

I find the use of these terms does the reader a disservice by giving them additional cognitive load.

You typically end up having to go back and read whatever was written again.

It's an interesting example to confuse most advanced `AI's. They just don't understand what `it' refers to in the first sentence.

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."

Double pronoun confusion

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.

The important bit is not overuse or underuse, it's proper use. I was taught in high school rhetoric class:

all pronouns must have a clear, one-word antecedent.

This principle was drilled into my brain, and it's helpful.

That is why scientific papers have so much "let x be ..."

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

Legal documents do this as well (albeit in different language, typically at the top of the document).

This is one of the most helpful critiques I've ever received in my college english classes

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.

Sometimes you just have to define variables. Customer C, supplier P, etc. That can get hard to read if done wrong, but better than dangling pronouns.

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.

Pronouns unclear, please type $username instead of "I".