Comment by bambax
9 hours ago
> 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.
> 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."
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.
Yes 100%.
There is no undercurrent or symbolism, just read the email as written please.
I became aphantasic at ~15 and spent years after interfacing with non tech people over the phone and email.
In English it's so damn hard to be precise compared to languages like Portuguese.
Also, LLMs blather so fucking much context is impossible to track wtf they are even writing about.
* Fast screenshotting and arrows/drawijg should be first class on all OSes.
3 replies →
> 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.
School, and specifically learning is not deterministic.
While we can automate away most things, human learning doesn't seem to be one of them.
2 replies →
Because the Junior eventually grows up to become a Senior, and they will be responsible for maintaining said automation.
1 reply →
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)
That's why having a long shell history is so great, you can just scroll back further to get more context, because it really captured everything.
Transcript
Your comment needs some documentation! ;oP
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.
You should take this up with someone in the org you trust
"All three clouds" is such a weird phrase.
There is no "cloud". There is other peoples hard drives.
But let's pretend the "clouds" you use are "clouds". Ok. What makes the other hosting providers not "clouds"? Bit of a no true Scotsman.
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.
1 reply →
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.