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.
  • Dr. Moose@lemmy.worldEnglish
    8·
    4 days ago

    all of these tips are moot because of SEO. If you want anyone to actually read your article you still have to write for both the reader and the search engine unfortunately.

    So, tips like the “Write clear headings” are often hard to actually implement as search engines prioritize keywords in headings and you’d be outranked by a dude who doesn’t do that 99% of the time.

  • copygirl@lemmy.blahaj.zoneEnglish
    18·
    4 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
      10·
      4 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…”

      • copygirl@lemmy.blahaj.zoneEnglish
        4·
        4 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
      41·
      4 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.

  • dajoho@sh.itjust.works
    72·
    4 days ago

    Am I the only one who finds the title abrasive? Why “rules”? Who are you and why should I listen to you? Will you send the tutorial police around if I ignore you? Maybe “recommendations” would be a better choice?

  • Ephera@lemmy.mlEnglish
    3·
    4 days ago

    If only this stuff wouldn’t eat so much time. I’ve been writing a library and it often feels like I’ll spend 1 hour documenting for maybe 5 hours of implementing a feature. And I’m not even terribly happy with the documentation yet. 🫠

  • BaldManGoomba@lemmy.world
    11·
    4 days ago

    Why not both? People are motivated or get things in different ways sometimes I just need the command other times I need to understand why. As for titles of sections the funny or longer chapter lines I might remember better than the simple one.

  • deroyonz@lemmy.zipEnglish
    33·
    4 days ago

    Think about the wording of the headings so that they communicate as much as possible without sacrificing brevity.

    Which of these tutorials would you rather read?

    1. Go
    2. Installation
    3. Hello, world!
    4. Deployment

    Or this?

    1. Why Choose Go?
    2. Install Go 1.23
    3. Create a Basic “Hello, World” Go App
    4. Deploy Your App to the Web

    honestly, neither of those? I get the general point, the first one looks careless and vague, but the second one looks AI generated and needlessly long, hard to skim for what I’m looking for. Why do the headers say Go 3 times when I already know I am in a Go article? Why is the specific version in that one header (even if you will be pointing them to a specific one in the content)?