Sep 22, 2026, 1:21 PM@MisuseCase
it's hard to write documentation for something you already know
also, people "good with computers" have absorbed so much of the unspoken patterns seen in computing that they mostly get by without documentation and it'a hard for them to figure out which parts may be unobvious to an average person
@dashdsrdash @ArneBab @tante
@wolf480pl @dashdsrdash @ArneBab @tante A few years ago I was responsible for ensuring security compliance for components of a large project. Doing this work required reviewing documentation of the components. I found that while all the documentation followed a common format, parts were often hastily copy-pasted or entered, and sometimes they were out of date.
/1
@wolf480pl @dashdsrdash @ArneBab @tante I would have to chase down someone on the team responsible for the component to get missing/current information. Sometimes the documentation about who was responsible for a component was out of date too, and the person I tried to reach was gone.
When I chased someone down for details about their project they sometimes asked me why Thing A had to be in the documentation anyway, didn’t everyone know Thing A worked like this?
/2
@wolf480pl @dashdsrdash @ArneBab @tante I would remind them that the project was a few years old and very large, different people were coming on board or leaving all the time, requirements had changed, and teams working on different things often didn’t talk directly to each other. So when documenting your feature you cannot assume prior knowledge and you need to be explicit about even the “obvious” stuff.
/3
@wolf480pl @dashdsrdash @ArneBab @tante Good documentation is a skill you can learn but it often involves questioning your assumptions and thinking about people outside of yourself and your immediate team. Many people (not just computer people) have a difficult time with that and even find it emotionally uncomfortable.
/end