I was trying to install a new open source project and was having a hell of a time. Nothing seemed to be working despite me following the tutorial to the letter. I was getting the most bizarre error messages and was on the verge of quitting to become a goat farmer, when I threw one last dice... I read the tutorial.
Previously I'd been copying and pasting the instructions as I went. One step said "Make sure the bauxite configuration command is set to true" but the code provided said
./configure --magic M --more-magic QxZp --bauxite false --turnip green -z
And there is was! I changed a false to a true and everything started working. Being the good netizen that I am, I sent a pull request to fix the documentation.
And then it struck me.
There's no CI/CD for documentation.
Oh, don't get me wrong. Things like OpenAPI can auto-generate documentation based on your code - but it can't write a "getting started" tutorial.
Looking back through the documentaion I'd encountered, it was clear that the tutorial had been wrong for a few years. It was a small project, so it wasn't hugely surprising that hordes of users hadn't complained. But, to me, it points to a general problem. I find this issue all the bloody time! Whether it is a big established project or a little indie gadget - I follow a tutorial only to find out it is missing a step, or assumes I have a library installed, or hasn't been updated for the latest version.
This is my plea to all developers. Spin up a fresh machine - without anything installed other than the base OS - and see if you can follow your own tutorial.
If you can't, rewrite it step-by-step until it works.