Open Source hot take: A software project is allowed to be *done*.
-
@MisuseCase @dashdsrdash @ArneBab @tante
The only thing worse than no documentation is stale documentation.
@paninid stale documentation is still better than blatantly wrong documentation that looks correct on the outside but teaches concepts wrong.
I tried letting an LLM summarize a programming book I wrote. It looked surprisingly good, until it was just plain wrong.
@MisuseCase @dashdsrdash @tante -
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante still copy pasting script written in BASH in the early 1990ies...
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante a side problem problem for me with this is when a piece of software is done it's impossible to tell whether it's actually still in maintenance mode, or if the author silently stopped caring and maintaining it.
Obviously the author doesn't owe me anything but I would like to know whether the software is abandoned -
@tante a side problem problem for me with this is when a piece of software is done it's impossible to tell whether it's actually still in maintenance mode, or if the author silently stopped caring and maintaining it.
Obviously the author doesn't owe me anything but I would like to know whether the software is abandoned@tante for some software it doensn't matter at all, for some it's very important -
@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
it's hard to write documentation for something you already knowalso, 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 -
Or, better, make it easy to add features without needing a fork. Provide clear and stable APIs and hooks for plugging in scripting languages.
No single program can capture 100% of all users' requirements. The goal for a Free Software project should always be:
- Implement the 90% of requirements that are common to most users.
- Make it easy for users to add the remaining 10% themselves.
- Make it easy for users who have the same 10%s to share their changes.
- Make it easy for users who have overlapping 10%s to share the common parts with other people, including overlapping sets of people.
Once you reach this point, you're done.
@david_chisnall @webbop @tante
Well, I do that for most of my recent personal projects, while being fully aware that I'm likely the only user of that project
I never regret it though, because designing extensible software is fun
-
@MisuseCase
it's hard to write documentation for something you already knowalso, 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 That may be why Stackoverflow worked so well.
Until its community got devastated by AI.
-
@MisuseCase
it's hard to write documentation for something you already knowalso, 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 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 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
-
@david_chisnall @webbop @tante
Well, I do that for most of my recent personal projects, while being fully aware that I'm likely the only user of that project
I never regret it though, because designing extensible software is fun
-
@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
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante It's a shame that this could be considered a hot take.
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
In industrial circles, the common version of this is
don't let the perfect be the enemy of the good
eg, to survive, you need to ship and sell products
another, cruder version
make shit, sell shit, ship shit -
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante In our language there is a proverb which means that a new bloom knows to sweep faster but an old bloom knows how to clean corners.
Your insight reminds me this ,exactly -
In industrial circles, the common version of this is
don't let the perfect be the enemy of the good
eg, to survive, you need to ship and sell products
another, cruder version
make shit, sell shit, ship shit@failedLyndonLaRouchite @tante I was pondering how at an “individual level”, most people actually crave for software staying still. How many pieces of software do I have where I explicitly stick with older versions? Actually pretty much every single one.
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante As an audio engineer, I don't fault other engineers who take on work (I guess) remixing or remastering songs/albums, but the USUAL reason that even happens at all has nothing to do with the ARTIST wanting it done.
It's some 30-something fuckwad running a social media campaign for a publishing conglomerate or streaming service who thought it would be fun to "refresh" the tracks with a modern twist or mAkE eVerYtHinG LoUdeR.
It was done with the original release.
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante this advice isn't specific to OSS either
-
Open Source hot take: A software project is allowed to be *done*. Not everything needs to add features or rewrite things. You can just be happy with functionality and focus on just maintainance. "Maintenance mode" is not always bad but can just show a mature product.
@tante It makes me think about this article: https://andrewkelley.me/post/why-we-cant-have-nice-software.html
-
@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.
Small bit of correction:
There is no intuitive software. At best, there is software which re-uses a common pattern, formalized or not, so that what you have learned previously is recognizably appropriate in this new system.
