Rules for Writing Software Tutorials
refactoringenglish.com
It's easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules.
  • kubica
    45•3 days ago

    I don’t quite agree that for a beginer being presented with

    sudo apt update && \
  sudo apt install --yes software-properties-common && \
  sudo add-apt-repository --yes ppa:deadsnakes/ppa && \
  sudo apt install --yes python3.9

    is better than

    sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.9

    All those symbols and “–yes” used to feel quite cryptic to me.

    • Eager EagleEnglish
      7•2 days ago

      The argument is that a beginner might not notice a command falls. The && prevents further execution.

      Personally I’ve seen that happen several times myself. Beginners are just not used to reading the cmd outputs and I can’t blame them. There are many CLI tools with awful error reporting out there.

      • @[email protected]
        6•2 days ago

        That’s why showing the expected outcome is also very important. It can feel very verbose, but the number of times I’ve been unclear as to if something worked because the documentation goes on immediately to the next step without demonstrating the success/failure states is extremely frustrating.

    • @Randelung
      6•2 days ago

      It’s not the same, though. One will stop if a previous command fails, the other will continue.

    • @SwordInStoneOP
      17•3 days ago

      yeah, I’d give it as 4 separate copy-pastable commands and then write “or as one command…”

    • @lunarul
      7•3 days ago

      If it’s a beginner trying to learn those commands, definitely the latter.

      If it’s a beginner trying to set up their environment for the actual thing they’re trying to learn, then a fire and forget single command is more user-friendly.