Posted by edent 14 hours ago
It is under 5 minutes to write a shell/bat/make/cmake script for each platform to configure library requirements, import OS specific data, and enable GPU/NPU features. Then run through the application build, installation package with stripped performance build, and or a few regression tests.
Lets say you have 4k downloads a month on a small project, and it takes 1 hour for each admin to read/configure. You just saved about 5 years of your users lives reading your document. =3
The hard truth is OSS is often chaotic as there is no authority saying a given API is "good-enough" to version freeze, and it limits how much individuals can integrate without upstream source-tree contiguous-integration at the mercy of 150k devs whims. =3
Flatpacks are great. I've barely ever had a problem with them, and the problems I did have were solvable with a cursory web search. Yes, they take up more space. That's a worthwhile trade-off in exchange for actually working.
For God's sake, this is not "biases," wtf?? That's straight up just not reading/following the document you're supposed to be testing/reviewing. When I test my documents I actually follow them exactly, step by step, and I always catch these sorts of mistakes. Always. I always copy/paste commands because I know that is what the customer will do, so I have to make sure that works flawlessly.
Dude, if you actually follow your own document, you don't have to pay people to do it for you. Also, you can make sure the person you are paying doesn't ignore the document like you apparently do.
I stopped reading, I'm not interested in whatever else this dude has to say. I'm literally flabbergasted.
Maybe it's because my documents have always gone to real paying customers who have to get through this install, and not some hobby project I'm super proud of or whatever and I don't think I'm super clever? Idk.
Having said that, I found consistently that when a project has working examples, ideally documented a bit, aka explained, they tend to work much better than those projects that have no examples. Working examples often also help get into a project quickly and check out how it works. It helps to learn too.
READMEs are not useless, of course, but the quality varies a lot. I also know of folks who use AI slop spam to improve it, but while it may improve a little bit, it generates a lot of horribly to read text that makes no sense. I am noticing this with the ruby core dev team - they (almost) all suddenly have perfect language skills but it is more like an advanced babelfish translator. What they piece together here makes no sense. Claude in particular is now famous for this slop content. And I don't understand what it is used: real people read any of this AI slop? Because I just skip it or filter it away these days.
Because theoretically you should be able to describe not only your entire application logic, but upper and lower bounds of inputs as well. Good code would describe this inherently.
Documentation is only useful when a) the application is not source available, so you have no choice, b) you want to save a human developer time for them to understand your code, or c) you want to use documentation as a cache hit for agent use (less token spend)