1. 73
  1. 29

    Perhaps related: I find that a certain amount of redundancy is very useful for error checking, both by the speaker/author and listener/reader. This might take several forms:

    • I repeat myself often when giving talks or writing, so you never have to jump too far back to an earlier point in time / space. If I say something that is very similar but slightly different than before, I’m either doing it to draw attention to an intentional change, or I’ve made a mistake! Either way, people are paying attention closely to the difference.

    • When writing math, I never rely on symbols or words alone, but a mixture of both. The rule I follow is that you should be able to understand the sentence even if most of the symbols are deleted. This is invaluable for catching mistakes, and also for establishing notation – using words alone can be imprecise, and using symbols alone might be disorienting for a student or for someone familiar with slightly different conventions. The document should be skimmable, and every theorem should be more or less self-contained.

    • When writing code, I prefer to comment each logical block with some explanation of “what, why, how”, even if an educated reader might be able to infer from context. The point is that if their inference about the code does not match my comments, then they can confidently conclude the code has a bug, and it’s not just some mysterious hack they should be afraid of changing. Yes, this means maintaining comments along with the code, but I find that to be good practice anyway.

    A good way to summarize might be: When communicating, it’s important to keep in mind the predictions / assumptions your audience will make about your speech / writing. They’ll spend a lot of cognitive effort working through the things you say that don’t match their predictions. So, make sure you only surprise them with the new information you’re trying to communicate, rather than potential distractions like unfamiliar notation or syntax. (non-standard notation is ok and sometimes preferable, but the meaning should be evident from context!)

    1. 9

      The rule I follow is that you should be able to understand the sentence even if most of the symbols are deleted.

      As someone bad at math, I appreciate you.

      1. 13

        Heavy use of symbols is an underappreciated roadblock for a lot of people who might otherwise be able to grasp math concepts, I think.

        As someone who didn’t study math beyond basic calculus, I’ve had the experience of being confronted with a page full of unfamiliar glyphs and having no idea what to make of it, but then understanding the idea just fine once someone translated it to English for me.

      2. 5

        In one concrete example, I try to never use “former” and “latter” to refer to previous things because it requires a jump. You can usually summarize the options in a small phrase.

        1. 3

          I wonder how many, like me, have to go through mental gymnastics to separate “former” and “latter”. I know latter comes after former because of the resemblance to “later”.

          1. 2

            I use the same mnemonic!

            Though I wouldn’t go so far as calling it gymnasgics (for me personally), I do think it inherently causes a pause to backtrack and re-parse.

            Another point for the Finnish language because of having a tighter coupling to all the other words referring to something earlier or later. I can’t remember how this is properly expressed in German or French, but Swedish also gets this quite correct.

            English just makes it unnecessarily difficult.

            1. 2

              I thought the English construction was somehow derived from French (or Norman, rather) but apparently it’s from Old English if this blog post is to believed: https://www.grammarly.com/blog/former-vs-latter/

        2. 2

          This is an underrated statements. I find that the “avoid needless words” sentiment does more harm than good, even in fiction, and can be disastrous in technical writing.

          Human speech naturally has some redundancy in it, and the higher the probability of errors and the higher the cost of those errors, the more redundancy is required. Clarity and redundancy aren’t mutually exclusive, sometimes clarity is redundancy.

          1. 1

            The point is that if their inference about the code does not match my comments, then they can confidently conclude the code has a bug, and it’s not just some mysterious hack they should be afraid of changing.

            Nitpicking: what if it’s the comments that are incorrect or out of sync with the code? With both code and comment, now you have two sources of truth…

            1. 9

              Exactly! If the code doesn’t do what the comments say it does, whoever is reading will file an issue and the matter will be sorted out. This redundancy is really helpful for hunting down bugs and avoids two problematic scenarios:

              1. If someone has changed the code but not the comment, they probably didn’t do a thorough enough job reading the surrounding context to actually understand the impact their changes will have on the rest of the code. So they’ve either introduced a bug, or they forgot to verbally explain the reason for their changes, which itself warrants a bug report.

              2. I feel that code takes on just as much (or more) technical debt when the documentation is missing as when the documentation is incorrect. Incorrect documentation (as long as it is colocated with the code it describes) can act as a big red flag that something is wrong. When documentation is missing, anyone who attempts to modify the code will be afraid to make any changes, afraid that the suspicious lines really do serve some mysterious purpose that they just don’t understand yet. If someone is afraid to make changes, they might instead add code to wrap the mysterious bits

              Some caveats:

              • It does take some discipline to work this way, and I haven’t tried enforcing this style in large codebases / large teams. I have seen it work well on smaller projects with one or two like-minded collaborators. It’s especially useful on solo projects where I might work on the project in bursts of a few days once every few months. This way I document my in-progress thought process and can be more confident that local changes to the code will work as intended, even if I haven’t touched the code in three months.

              • For documentation that is not written inline with the code itself, and intended to be consumed by users of the software, not developers, I feel differently about missing vs incorrect documentation. In this scenario, it’s much harder to keep the documentation in sync, and incorrect documentation is more dangerous.

              1. 4

                I think that’s the point, just like parity bits on memory. At least you know something isn’t right.

            2. 10

              I found the Google Technical Writing course to be excellent in providing further tuition in the subject.

              TIL about https://developers.google.com/tech-writing - looks very interesting.

              1. 5

                I think clarity of communication is one of the most underrated skills as a developer. If the ratio of reading code to writing code is 10:1 then the ratio of talking about code to writing code must be 100:1

                So, barring overtime, a truly senior developer must average no more than 24 minutes a week coding? Possible, for some people who have the title “architect”, but I doubt it’s true of that many developers. I hope that if I ever reach that point, it’s because my title is manager/consultant/whatever else.

                1. 3

                  I interpret these ratios as applying to time over the life of code, possibly including many people.

                  Also, I am not aware of empirical studies that justify the stated ratios. I interpret them mostly as placeholders used to make a (useful) point.

                  1. 2

                    I definitely know multiple people for whom this is true.

                    I hope to avoid such a fate myself but it absolutely happens.

                    1. 2

                      The majority of my time is doing operational stuff nowadays, and I frequently read code but am not an “official” developer on any of the projects whose code I’m reading. The ratio of loc read / loc written is > 10 for me for many projects.

                    2. 4

                      Wow, I’m it’s cool that something like https://developers.google.com/tech-writing exists. I have a sense of what I consider to be “good technical writing”, and I’m excited by the possibility that other people have given words to that sense. Does anyone know of other resources about technical writing?

                        1. 2

                          Thank you :)