Can you follow your own getting started guide?
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.
The deficiency you identify is remarkable only when it's absent.
| Reply to original comment on mastodon.social
Dom says:
| Reply to original comment on mastodon.xyz
| Reply to original comment on mastodon.social
Johannes Rexx says:
Failing to indicate to first clone a repository and cd into the project directory, and then issue a bunch of commands.
Failing to provide a complete list of dependencies, for example package
abc-devyarn, npm, pnpm et. al. don't work the same way, one may work, another does not
Build instructions that are old and don't work on contemporary distros anymore
nicopap says:
Now it just feels like running around naked when I don't have the safety blanket of a tool that tests my examples.
I believe @nevonnen had an idea about executable markdown files sometime around a decade ago. That seems like it could be a useful approach.
More comments on Mastodon.