> But it is really hard to ignore your own biases. Of course you know that certain commands require sudo and obviously when you wrote -foo you meant --foo and everyone knows that you have to reboot afterwards.
I sometimes write readmes for myself, so that I can remember the exact steps to generate a data report, etc.
It's surprising how much they become incomprehensible after just a couple of weeks; when everything's in our head it's all clear, fluid and self-explanatory; but once we have forgotten the context, nothing makes sense anymore.
Most people don't think linguistically, we have way more conceptual thinking. What makes it difficult is we rarely realize we are thinking conceptually when writing because these concepts occur automatically and we don't notice it.
In school this lead to a lot of difficulties for me, one in writing those comments out for other people to understand, but the other seemed to be that when reading the average statements used in education for teaching I could map the same strings of language to multiple and sometimes conflicting statements because of the inexactness of the language used.
It turns out explaining concepts while leaving little room for different interpretation is hard.
As someone who does think linguistically, I often end up at odds with people who are expecting me to imply things in my text, when my text is written specifically to convey exactly what I mean and nothing further.
I learned about it in high school, and that was 80s/90s but not by name per se. I took the ASVAB and there were questions like "fold a piece of paper in half twice, punch holes in a pattern, and then pick which image would be the result when the paper is unfolded" that I thought were ridiculously easy. I was told that they were difficult for people that cannot form mental images and these help test that ability.
> While the loss of mental imagery following brain lesions was first described more than a century ago, the key cerebral areas involved remain elusive. Here we report neuropsychological data from an architect (PL518) who lost his ability for visual imagery following a bilateral posterior cerebral artery (PCA) stroke. We compare his profile to three other patients with bilateral PCA stroke and another architect with a large PCA lesion confined to the right hemisphere. We also compare structural images of their lesions, aiming to delineate cerebral areas selectively lesioned in acquired aphantasia. When comparing the neuropsychological profile and structural magnetic resonance imaging (MRI) for the aphantasic architect PL518 to patients with either a comparable background (an architect) or bilateral PCA lesions, we find: (1) there is a large overlap of cognitive deficits between patients, with the very notable exception of aphantasia which only occurs in PL518, and (2) there is large overlap of the patients’ lesions. The only areas of selective lesion in PL518 is a small patch in the left fusiform gyrus as well as part of the right lingual gyrus. We suggest that these areas, and perhaps in particular the region in the left fusiform gyrus, play an important role in the cerebral network involved in visual imagery.
> It turns out explaining concepts while leaving little room for different interpretation is hard.
This pops up as one of the annoying aspects of LLM writing, at least for coding models. They are always saying things like "this test only establishes this, not that." Much of the time, what they say is either obvious, or you get to thinking "maybe the test should establish the other thing as well."
> explaining concepts while leaving little room for different interpretation is hard
To play devil's advocate: explaining concepts while leaving little room for different interpretation is also pointless. If you don't care about the interlocutor's interpretation, then why are you even talking to them? If the task is really deterministic, then automate it.
You have to learn the rules before you know which ones can be bent and which ones can be broken.
The problem I have is that when I'm asked to follow a procedure that you know just while reading it was created by someone with less experience and better/faster/cheaper ways are available to get to the same result. Deviation will however get you into trouble because the procedure is what is vetted and approved. Deviations from procedure could open one up to liability if things later do not work as expected.
Yea, that's what I was trying to get at. It is not deterministic because the interpretation is the point. It is how the learner integrates the material. If you don't interpret, then you're not learning, you're just memorizing.
A teacher should therefore embrace the fuzzy nature of explaining concepts.
With humans it is a mix of both. Learning just the algorithm is hard, you need some amount of initial data to conceptualize, and this amount of data can vary pretty greatly between people.
I find that writing this documentation is both a "muscle" and gets better with experience.
e.g. as you both write documentation and see yourself or others use it, you start to get a feel for what people tend to understand and how to communicate it.
You can also do "dog fooding" where one person or group writes the docs and then other people follow them. If you iterate on this quickly, you can get to really good docs in a short amount of time.
The one thing I have found that really helps here, for self-directed documentation, is to write it for a modified version of yourself.
You may still be the audience. But you will be four or five years older, shit will have gone on in your life, you will have more to remember, you will be tired, you will have less patience, you will resent being forced to do archaeology on yourself, and have a dim view of the irresponsible young scamp who thinks he has an excellent memory that you are right now.
Write for that person and your documentation will be better.
(As you may be able to tell, I am now that person. And I fear there are two more cycles of this to go)
My boss gives me shit regularly for not remembering things. He doesn’t seem to understand that when you manage environments in all three clouds, storage arrays in four different countries from different manufacturers, four on prem virtual clusters, Active Directory, entra, etc that you can’t remember everything all the time if you haven’t touched it in a while.
I started a daily journal when my team’s workload got to be so much that we can’t remember everything. It helps, but even going back to it weeks later there were things I did not write down because I assumed I’d remember them later.
I’ve since gotten better at being more comprehensive, and trying to think in the “how to make a sandwich” way of instruction. I’m not being condescending to my future self, I know my future self has too much shit to mange to remember it all.
So long as you know where to look and can quickly check, not remembering is OK. If your boss wants you to remember everything of the top of your head, he's being a knobhead.
This useless and obnoxious criticism actually ties into TFA a bit: when GP was writing for this audience, they wrote in a way that wasn't overly precise, but specific enough that we'd understand their point.
This comment actually ties into the GP's point about how when you get further from the context, not being overly precise will lead us to eventually not understanding that part of the point.
I just went and looked at the first equivalent documentation that I wrote to myself in 2009 explaining how to automate mounting disks via fstab. It's very complete. I was tripped up on documentation that I wrote to myself in the past year only a week ago because my understanding of *nix systems now causes blindspots when writing to future-me.
My new test is to ask an LLM questions about the documentation and see if it gets correct answers. I wonder if this will become a common QA step for the docs at some point, it's very useful for finding gaps in the docs or things that are unclear.
I sometimes write readmes for myself, so that I can remember the exact steps to generate a data report, etc.
It's surprising how much they become incomprehensible after just a couple of weeks; when everything's in our head it's all clear, fluid and self-explanatory; but once we have forgotten the context, nothing makes sense anymore.