@tante Aren’t most Free Software projects done?
From time to time they are adapted to changes in the environment or otherwise changed expectations, but usually stuff just works.
Maybe a problem is that when we use grep or sed, we don’t realize that these are projects, too, because they don’t make the headlines.
@tante maybe a way to deal with that could be to write more often about the tools that already exist.
I remember how the university provided training all the time about citation management with Zotero, but there wasn’t a single training about bibtex.
Even though that is ingrained into many academic workflows and usually just works.
The mantra of the last 25+ years has been that desktop computing is easy and ubiquitous and all programs should be easy.
Because they are easy, they do not require manuals or good documentation and most importantly, do not require training and education.
The reality is that every field of endeavor is complex and messy and has lots of stuff to learn. Management gravitates to "it looks easier, so it must work better" and this is almost always incorrect.
Meanwhile, many people have adopted the idea that they "aren't good at computers" when in reality they have never been taught and don't even realize what there is to learn.
@dashdsrdash @ArneBab @tante It’s possible (but difficult) to design software to be intuitive and easy to use. It’s easier to write good documentation but nobody wants to do it. This is why so many projects give the documentation work to AI now even though it’s not very good. They kind of understand that they are supposed to have documentation but don’t want to do it and don’t *really* understand what the purpose/goal of documentation is.
@MisuseCase @dashdsrdash @ArneBab @tante
The only thing worse than no documentation is stale documentation.
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