Can you follow your own getting started guide?

By on   6 comments 350 words, read ~159 times.

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.

Share this post on…

6 thoughts on “Can you follow your own getting started guide?

  1. says:

    @Edent I'm a very highly experience failure in computing.Doubtless this is in part due to congenital idiocy.However spending 100s of hours not getting programs to work has, I believe, contributed somewhat to my miniscule progress over the decades.And also contributed to my hatred of computers, most website designers and hobbyist-level software that passes itself off as ready for domestic use.

    The deficiency you identify is remarkable only when it's absent.

  2. says:

    @Edent Software documentation can be the worst! I also don't like it when I visit a project page and there is no description of what it does, but there's either investor-speak or point update information. "Why do I want this module?" feels to me to be the best use of a root url.

  3. @Edent I'm reading "The Design of Everyday Things" by Donald Norman right now, he points out that people very often think it is their fault that they don't understand how something works (spoiler alert: it's not - it's bad design or communication). So that may be a reason why the tutorial had been wrong for a few years. I work with many "non-technical" people - they simply give up in these cases.

  4. Johannes Rexx says:

    Sins I see far too often include:

    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-dev
    yarn, 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

  5. nicopap says:

    The rust programming language toolchain has a built-in testing tool that — in addition to running unit tests — scraps documentation for examples and run them, this way, examples are always up-to-date.

    Now it just feels like running around naked when I don't have the safety blanket of a tool that tests my examples.


What are your reckons?

All comments are moderated and may not be published immediately. Your email address will not be published.