The Academy

Loading the search index…

Searches the academy on this device only.

Reading documentation and searching for error messages

Learn to read official documentation, compare sources of different quality, search for an error message effectively and test a suggested fix safely.

30 minintermediateUbuntu/LinuxWindowsPractical task needs a laptop or desktop

Marking a lesson as read does not prove you can do it. Skills count as demonstrated when you pass the quiz (not yet) and complete the practical tasks (not yet).

By the end of this lesson you will be able to

  • Find and read the official documentation for a program, command or setting.
  • Pick out the exact words of an error message and turn them into a good search.
  • Compare answers from several sources and decide which to trust.
  • Test a suggested fix safely, with a way back, before applying it for real.

No course can teach every program, and software keeps changing. The skill that outlasts everything else is knowing how to find out for yourself. Experienced people do not remember everything: they read documentation quickly and they search well. This lesson shows you how to do both, and how to avoid the danger of copying advice from the internet without understanding it.

Why documentation comes first

Documentation is the official explanation written by the people who make a product. It is usually the most accurate source, because they know exactly what the product does. A forum post or video may be shorter and friendlier, but it can be out of date, written for another version, or simply wrong. A good habit is to start with the official pages, then use other sources to fill gaps and to understand them. Think of documentation as the manufacturer's manual for a kettle, and forums as neighbours' advice about the same kettle: both are useful, but the manual tells you what is true.

Documentation comes in several forms. There is a reference, which lists every option precisely and is good for checking a detail. There is a guide or tutorial, which walks through a task in order and is good for learning. There is a FAQ, with answers to common questions. And there are Release notes, which list what changed in each version and explain why a setting you remember is no longer where it was.

Diagram

Four kinds of official documentation and when to reach for each.

Reference
  • Every option, exactly
  • Precise but dry
  • Check one detail
Guide
  • Steps in order
  • Explains why
  • Learn a new task
FAQ
  • Short answers
  • Common problems
  • Quick fix attempt
Release notes
  • What changed
  • Version by version
  • After an update
Four kinds of official documentation and when to reach for each.
Read this figure as text

Four columns describing reference, guide, FAQ and release notes.

Four columns. Reference: lists every option exactly; use it to check one detail. Guide or tutorial: steps in order; use it to learn a task for the first time. FAQ: short answers to common questions; use it when your problem is probably common. Release notes: what changed in each version; use it when something moved or stopped working after an update.

Help that is already on your computer

Before you open a browser, remember that the computer has its own help. On the command line, most commands explain themselves. The Man page is the built-in manual of a command on Ubuntu; the --help option prints a short summary; on Windows PowerShell the Get-Help command does the same job. These commands only read information, so they are safe to run anywhere.

Reading the built-in help

Open a terminal first. These commands only display text.

man ls opens the manual page for the ls command, which lists folder contents. Press Space to go down a page, / followed by a word to search inside it, and q to quit. ls --help prints a shorter summary directly in the terminal. Look for the sections called NAME, SYNOPSIS (the pattern for using it) and DESCRIPTION, which lists each option and what it does.

Terminal (Linux) · you can run this on your own computer
man ls
ls --help

  1. Step 1: Open the manual

    Type man ls and press Enter.

    You should see: A page headed LS(1) fills the terminal, starting with NAME and SYNOPSIS.

  2. Step 2: Search inside it

    Type /human and press Enter.

    You should see: The word human is highlighted, in the description of the -h option.

  3. Step 3: Leave

    Press q.

    You should see: You return to the normal prompt.

How to read documentation without drowning

Documentation is long, and nobody reads it all. Read it with a question in mind. Check the title and the version or date first, to be sure it matches the system you have: Ubuntu 24.04 and Windows 11 have pages of their own. Skim the headings to find the part that matches your question, read that part slowly, and look for examples you can copy and adapt. Pay attention to words such as warning, note and deprecated, which tell you about dangers and about features that are being removed.

Simulated interface: not a real screenshot

Where to look on a documentation page, in order.

https://docs.example.org/guide/copying-files

Copying files

Applies to version 24.04

Example: cp report.txt backup/

Note: if a file with the same name exists, it is overwritten.

  1. Marker 1: Who published it
  2. Marker 2: Does the title fit?
  3. Marker 3: Right version?
  4. Marker 4: Worked example
  5. Marker 5: Read the warning
Where to look on a documentation page, in order.
Read this figure as text

A simulated documentation page in a browser with numbered marks on its title, version, headings, example and warning.

A simulated browser window showing a made-up documentation page at docs.example.org. Marker 1 points to the address, which shows who published it. Marker 2 points to the page title, Copying files. Marker 3 points to a line, Applies to version 24.04, which tells you whether the page matches your system. Marker 4 points to a worked example. Marker 5 points to a note that warns the command overwrites files with the same name.

An Error message is a clue written by the program that failed. Copy it exactly, because the wording is what other people searched for and posted about. Remove the parts that are only yours, such as your user name, your folder names and any private addresses, and keep the parts that are the same for everyone. Add the name of the program and your system, such as Ubuntu 24.04 or Windows 11. Put the fixed phrase in quotation marks if it is long, which asks the search engine to match it as written, as in the search operator lesson.

Diagram

Splitting an error message into the parts that matter for a search.

bash:ProgramInclude it
cd:CommandInclude it
documents:Your own nameLeave it out
No such file or directoryThe problem phraseSearch for it
Splitting an error message into the parts that matter for a search.
Read this figure as text

An error message split into program name, your own path and the general problem phrase.

The text bash: cd: documents: No such file or directory is split into four parts. bash: the program that complained, a good word to include. cd: the command that failed, also useful. documents: your own folder name, specific to you, so leave it out of the search. No such file or directory: the general problem phrase, which is the best part to search for, in quotation marks.

Here is that error in a terminal. The learner typed cd documents while in a folder where no such folder exists (the real name starts with a capital letter, Documents). The message tells you something precise: the shell looked for a folder by that exact name and did not find it. Linux treats capital and small letters as different, so the fix is a spelling fix, not a repair. This is a good example of how reading the message before searching can solve the problem at once.

Simulated interface: not a real screenshot

A common error, and what to read in it.

Terminal (simulated)
  1. Marker 1: Read the message first
  2. Marker 2: Look at what really exists
  3. Marker 3: Capital letter fixed it
A common error, and what to read in it.
Read this figure as text

A simulated terminal where the command cd documents fails and cd Documents works.

A simulated bash terminal in the home folder. The learner types cd documents and the terminal prints bash: cd: documents: No such file or directory, marked 1. The learner then types ls and sees folder names including Documents with a capital D, marked 2. The learner types cd Documents and the prompt changes to the Documents folder, marked 3, showing the fix was the capital letter.

Comparing answers and testing safely

Search results will give you many answers. Do not copy the first one. Ask: does it come from the official documentation or a known organisation? Is it recent and written for my version? Do several independent sources agree? Does the person explain why the fix works? An answer that explains why lets you check it against what you know, and an answer that says only paste this is a warning sign.

Diagram

A decision path before you apply advice you found online.

  • Do I understand what the fix does?
    • YesIs it from official or trusted sources that explain why?
      • YesCan I undo it, with a backup?
        • YesDo thisApply it to one small thing or a practice copy, and check the result.
        • NoDo thisBack up, then return to this question.
      • NoDo two independent sources agree?
        • YesCan I undo it, with a backup?
          • YesDo thisApply it to one small thing or a practice copy, and check the result.
          • NoDo thisBack up, then return to this question.
        • NoDo thisDo not run it. Ask a knowledgeable person or choose another approach.
    • NoAfter reading the docs, do I understand it now?
      • YesIs it from official or trusted sources that explain why?
        • YesCan I undo it, with a backup?
          • YesDo thisApply it to one small thing or a practice copy, and check the result.
          • NoDo thisBack up, then return to this question.
        • NoDo two independent sources agree?
          • YesCan I undo it, with a backup?
            • YesDo thisApply it to one small thing or a practice copy, and check the result.
            • NoDo thisBack up, then return to this question.
          • NoDo thisDo not run it. Ask a knowledgeable person or choose another approach.
      • NoDo thisDo not run it. Ask a knowledgeable person or choose another approach.
A decision path before you apply advice you found online.
Read this figure as text

A yes or no decision tree for whether to apply a suggested fix.

Start: Do I understand what the fix does? If no, look up each part in the documentation; if still no, do not run it. If yes: Does it come from the official documentation or a trusted source that explains why? If no, find a second source. If yes: Can I undo it, with a backup or restore point? If no, make a backup first. If yes: Try it on a practice copy or one small thing, then check the result.

Change one thing at a time, and note what you did, so that you can tell which change had which effect. If the first fix does not work, undo it before you try the next, otherwise you build up several half changes and cannot tell what caused what.

Common mistakes

  • ✖ Instead of: Pasting a fix from a forum without knowing what it does.

    ✔ Do this: Understand each part, check the documentation, and test it somewhere safe first.

  • ✖ Instead of: Searching with the whole message including your own file names and user name.

    ✔ Do this: Keep the program name and the general problem phrase, and remove private details.

  • ✖ Instead of: Reading documentation for a different version of the system.

    ✔ Do this: Check the version or date on the page and look for the page for Ubuntu 24.04 or Windows 11.

  • ✖ Instead of: Trying five fixes at once.

    ✔ Do this: Change one thing at a time and undo it if it does not help, so you know what worked.

If something goes wrong

man says No manual entry for a command.
Check the spelling. Some commands are built into the shell and are documented under help, such as help cd. Otherwise use the program's --help option or its official website.
Every search result is about a different problem.
Remove words that are specific to you, add the program name and version, and try the exact message in quotation marks. If there are still no good results, look at the official documentation index or ask a precise question, as in the next lesson.
The documentation uses words I do not know.
Look up each word in the glossary or a trusted dictionary. Try the guide or tutorial version of the page, which is usually gentler than the reference.
Two good sources give opposite advice.
Check the dates and versions of each, since advice often differs between releases. Prefer the official page for your version, and test the safer option first.

Key terms

Documentation
The official written explanation of how a product, command or tool works.
Release notes
A list written by the makers of software that says what changed in a version.
Error message
A message from the computer or program that says something went wrong and often where and why.
Man page
The built-in manual page for a command, opened with man and closed with q.
search operator
A search operator is a small symbol or word, such as quotation marks or a minus sign, that tells a search engine exactly how to treat your words.

Practise it for real

Reading is not the same as being able to do it. Complete these on your own computer, then tick only what you have actually done. These ticks are your own honest record: nothing checks them for you.

Guided exerciseNeeds a laptop or desktop

Read built-in help and search for an error

Use the built-in help: on Ubuntu run man ls and find the option that prints sizes in a human-readable way; on Windows run Get-Help Get-ChildItem -Examples. Then cause a harmless error on purpose: in your practice folder type cd nosuchfolder and read the message. Write the search you would make, with the private part removed, and find an official page that explains it. Write down the page title, publisher and version.

You have succeeded when:
Independent challengeNeeds a laptop or desktop

Challenge: compare three answers

Choose a small harmless question, such as how to change the screen brightness shortcut or how to show hidden files in your file manager. Find three answers from different places. For each, write who published it, its date, which version it targets, whether it explains why, and whether you would trust it. Choose one, test it on something safe, and write what happened.

You have succeeded when:

Knowledge check

6 questions. You need 80% to pass. Mistakes here are part of learning, and you can retry as often as you like.

  1. Question 1.Why start with the official documentation?
  2. Question 2.When searching for an error message you should include your own user name and private folder names so the search is accurate.
  3. Question 3.Match each kind of documentation to when you use it.
  4. Question 4.Wanjiru finds a forum answer for a slow laptop: paste a long command that begins with sudo and ends with a web address she does not recognise. The poster does not explain it.What should she do?
  5. Question 5.Put the steps in the safest order for applying a fix found online.
    1. Make sure you can undo it
    2. Understand what the fix does
    3. Check it against a trusted source
    4. Try it on one small thing
    5. Check the result and note what you did
  6. Question 6.A terminal says bash: cd: documents: No such file or directory, yet a folder called Documents exists. What is the most likely cause?

Summary

  • Start with official documentation and check that the version matches yours.
  • Use the help already on the computer: man and --help on Ubuntu, Get-Help on Windows.
  • Search the general phrase of an error message and leave out your private names.
  • Compare more than one source and prefer answers that explain why.
  • Never run a command you do not understand, and test one change at a time.

Checklist: can you do these?

Marking a lesson as read does not prove you can do it. Skills count as demonstrated when you pass the quiz (not yet) and complete the practical tasks (not yet).

Related lessons

References and further reading

Official sources for details that can change between versions.

On this page