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.
  • copygirlEnglish
    24·
    3 days ago

    Is providing a number of commands to use that require user input really that bad? When people start tinkering with the command line, first of all they shouldn’t trust just anything on the website blindly, which at the very least requires a basic understanding of how to enter commands, and respond to the terminal asking for input. The following “bad” example…

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

    …is instead turned into this single command with even more confusing syntax for beginners:

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

    Sure, it’s convenient, but if you just throw blocks of code at people to run, are they really learning anything?

    A better approach would be to have a quick tutorial on how to use the terminal and what the $ and # symbols mean (though they could be CSS decorators that can’t be copied), what sudo is and warning people about running untrusted commands on their system. Then you just link to that at the top saying something along the lines of “if you’re unfamiliar with running commands, and the following seems confusing, check this quick summary”, behind a question mark icon connected to each block of commands, or similar.

    • SwordInStone@lemmy.worldOP
      12·
      3 days ago

      I absolutely abhor it when the command includes $ that copies with it. It means nothing to the beginner’s and the pros know it is a command.

      I wrote under other comment:

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

      • copygirlEnglish
        6·
        3 days ago

        Yeah, it should not be part of the text just like line numbers shouldn’t be part of the code on a code hosting site, yet it can be visible, no? Later it does recommend using $ to distinguish command and output. Is it now okay for a beginner to be confused about what it means?

    • MonkderVierte@lemmy.ml
      7·
      3 days ago

      Rule number one: be wary of ppa.

      Rule number two: they work only on Ubuntu, they will break your Debian or Debian derivative.