The problems of writing simple instructions for new users to Linux

The first problem that you have to overcome is the terminology that we, as Linux Users, use day to day that the new user has no idea what it is you are talking about.

The Terminal – This is the mythical beast that everyone thinks linux runs from. They will generally have no idea what it is or what it does so telling someone to “Open the terminal with [Ctrl+alt+T] {assuming the distro has that as a short cut} and then copy this command into the terminal “sudo apt update”

They will copy it – move to the window and generally ctrl+v if they are a general Windows user. This will be the first fail as a lot of Terminals will not accept ctrl+v as a paste command.

Going back a step – how many web pages have you seen show

$ sudo apt update and the user will copy the $ as well. So you immediately have to think about the formatting your instructions will take.

Moving on again, so this leads to you needing to show them, first of all, how to use the mouse to ctrl+paste (Lets hope the terminal you are in accepts mouse controls)

So you see where this is going. You cannot write simple generic instructions to do something as there will always be something specific to the Linux Distro you are using that will not work.

So this leads you down the rabbit hole of giving them, say, three alternative ways to do something in the hope it will work with the OS they are using.

If the OS you are using has a wiki page, one written in “Simple English” - it may well be worth while asking the new user to look at this first to determine how this particular OS will work. The problem there will be, did they write a “Basic” section to cover what a new user will need to understand. Hmm this brings us back to the discussion – What is a “new user” - new to linux and new to computers – new to linux but very adept at using a computer.

So here we are half way down the first page and we have not even begun to address the instructions needed to do the tasks they need to complete.

So let’s, as a group, see if we can brain storm and get a blue print to write “User Instructions”

Where would you start, what would your template begin to look like.

  1. What is the Program/Command going to give instructions for.
  2. Can this be done point and click via a Software Manager or utility or will we have to write “Teminal Commands”
  3. ??

spot the command mistake in this doc too??


@Zeb thanks for bringing up this topic. I have also read and heard a lot discussion that takes this back one additional step before you come up with a style for User Instructions. How will you organize the User Instructions. Will you organize the instructions by the task you want to accomplish (i.e. “I need my Nvidia drivers” or “I need to send an email” or “I need to organize my digital photos”) or by a methodical approach that starts with explaining what the new user first sees (i.e. desktop, desktop icons, menu button, tray icons etc.) and moves to deeper and deeper information that eventually takes you to a terminal and the CLI?

I remember when I introduced my son to Linux two years ago, the most he had done before touching Linux was to surf the internet, use Google Apps, and use MS Word and PowerPoint in school. We started with what he wanted to do, “write programs in C++”. With Raspian he had everything he needed to get started installed, but I soon had to show him the CLI because GUI programs ran so slow on that 1st generation RPi and he could run gcc from the CLI too. Once he started writing example C++ programs that only ran in the CLI he started to wonder why everyone didn’t use their computer in this way using the terminal to accomplish everyday tasks. Then I showed him vim, and now two years latter he teaches me his vim ninja skills. :blush:


You it so many nails on this one. Do this for me. If you come across a wiki with openSUSE when drilling about, that doesn’t seem clear, please forward it to me here or Telegram or wherever and I will endeavor to make that wiki as clear as possible. I do try my best in making things seem straight forward but I know that I can miss the mark there too.

1 Like

This is an excellent topic that is near and dear to me as training and supporting users was always a primary task for me. It is always a challenge to be as specific as possible and even more so when putting out documentation for an unknown audience who you have to assume has little to no knowledge or familiarity with computers. As you mention, even the simplest thing like pasting a command can present a challenge that will force a user to give up. I think it would be a worthwhile exercise to pick a topic and work on a set of instructions to see how specific we could make it and whether a novice user could follow them successfully.

Another thought I had was how reliant I have become on good video content. Seeing someone work through a set of instructions conveys essential details that can be difficult or impossible to do with the written word. I will almost always search YouTube for a video when having an issue before turning to the internet as a whole.

1 Like

I like creating content that anyone can follow. But there’s always a point where you have to decide how much hand-holding you’re actually going to do so that you have the right info, but aren’t spending too much time on each little step. An example is showing how to install a distro; do you really have to include HOW to get the .iso file onto a USB stick to be able to boot from it? I typically skip this, but I have other videos on how to do that as well. There’s always a fine line between good content, and too many details.

What might help a tutorial is a prerequisites section:

Before attempting this tutorial, you must be familiar with:

  • Entering commands in a terminal
  • Changing directories and listing files
  • ect

Providing links to the above would be a bonus.

1 Like

This is a great point. Set expectations up front so someone doesn’t get frustrated half way through.

This would be a good free resource to point them too for learning the terminal