Finding technical documentation¶

Exercise finding-technical-documentation-annex.pdf · PDF

Yesterday Git threw an error message at you that you had never seen before. What did you do? You asked a classmate, you asked the teacher, or you pasted it into a search box. Fair enough. But in July none of us will be there — and in your first job, nobody will have time to answer every question.

Every technician, however senior, looks things up all day. The difference between a beginner and a professional is not knowing everything: it is knowing where to look, in what order, and whom to believe. Get that wrong and you may copy a command from a stranger that leaves a server open to everybody.

The ladder of sources¶

Technical documentation is any written explanation of how a program or system works and how to use it: manuals, help texts, wikis, guides.

Not all of it is equally trustworthy. Picture a ladder with five steps. The higher the step, the more you can trust it.

The rule of the ladder: go down to find an idea quickly; climb back up to prove it before you run it on a server.

flowchart BT
    S5["<b>5 · Blogs, videos, AI</b><br>fast idea, nobody answers for it"] --> S4["<b>4 · Forums, Q&A sites</b><br>someone had your error"]
    S4 --> S3["<b>3 · Community wikis</b><br>many eyes"]
    S3 --> S2["<b>2 · Official docs</b><br>written by the makers"]
    S2 --> S1["<b>1 · The program itself</b><br>your exact version"]

Step 1: ask the machine first¶

--help: the short version¶

Almost every command prints a summary of its options with --help:

ls --help

Among many lines you find:

  -h, --human-readable       with -l and -s, print sizes like 1K 234M 2G etc.

Long output? Filter it with grep, the tool you already know:

tar --help | grep exclude

One of the lines is --exclude=PATTERN, "exclude files, given as a PATTERN".

man: the full manual¶

A man page (manual page) is the complete reference of a command, installed together with it.

man git-commit

A man page opens inside less, the pager from Unit 4. You do not read it top to bottom — you search inside it:

Searching /amend tells you that --amend replaces the last commit with a new one instead of adding another.

man -k: when you don't know the name¶

You want to change when a password expires, but you don't know which command does it. Search the descriptions of all man pages:

man -k password

Among the results:

chage (1)            - change user password expiry information

The command is chage. If man -k prints "nothing appropriate" for everything, the manual index was never built; sudo mandb builds it in about a minute.

Sections: the number in brackets¶

There can be more than one page with the same name. Look:

whatis passwd

passwd (1)           - change user password
passwd (5)           - the password file

Some machines also show passwd (1ssl). The number in brackets is the section of the manual:

man passwd opens section 1, the command. To read about the file /etc/passwd, ask for section 5:

man 5 passwd

It tells you each line has seven fields separated by :, and the third one is the numerical user ID. When you see passwd(5) written in a document, it means "the page passwd in section 5".

help: for commands built into Bash¶

type cd

cd is a shell builtin

cd is not a separate program: it is part of Bash itself. That is why man cd answers No manual entry for cd. Builtins have their own help:

help cd

/usr/share/doc: the extras¶

Every Debian package can leave extra files in /usr/share/doc/<package>/: the copyright file you used to prove licences, changelogs, sometimes examples.

Ask the web, with care¶

Search operators¶

A search operator is a special word or symbol that tells the search engine how to filter the results.

These are all in Google's own help page, and most engines accept them:

The best trick of all: paste the error message in quotes, and add site: with the official documentation.

"connection refused" site:debian.org

Five checks for any source¶

Before you believe a source, ask:

1. Who wrote it?
2. When?
3. For which version and which system?
4. Does it explain why, or only say "paste this"?
5. Where else is it confirmed?

Try them on two sources for the same problem — your Samba share answers "access denied":

Source X fails four checks. And remember Unit 5: 777 gives read, write and execute permission to everybody, recursively, on every file under /srv. It "works" — the share opens, you move on — and now anyone can delete the company's files.

Where AI sits on the ladder¶

Course rule, again: the only AI allowed here is cs50.ai, as a tutor. On the ladder it sits on step 5: fast, fluent, with no author and no date. Use it the way you would use a classmate — to get an idea and the right words to search for. Then climb: does man say the same?

One more reason to climb: the option an AI gives you may belong to another version of the program. The man page on your machine cannot make that mistake. The AI knows text written about many systems; your man page knows yours.

Cite what you used¶

From now on, every page of your documentation repository ends with its sources. A reference is complete when a stranger can find it again, so it needs four things: title, publisher, address and the date you read it.

- Setting up a share — Samba Wiki — https://wiki.samba.org/... — read 28/05/2027

The Exercise sheet ends by adding a docs/08-references.md page to your tramuntana-docs repository with three sources you really used in Unit 6, then committing and pushing it, as you learnt in the Git sessions.

Key takeaways¶

• Climb the ladder: the program itself, official docs, community wikis, forums, then blogs, videos and AI. Go down for ideas, climb up for proof.
• --help for a summary, man page for the full reference (search with /word, n, q), man -k when you don't know the name, help for Bash builtins.
• The number in brackets is the manual section: 1 commands, 5 file formats, 8 administration — man 5 passwd is the file, not the command.
• Search operators ("...", site:, -word, filetype:, after:) turn a thousand results into the right ten.
• Judge every source with five checks: who, when, which version, why, where else.
• A reference needs a title, a publisher, an address and the date you read it.

Quick check¶

You now know where good documentation comes from. Next you start producing it: the same Markdown you have written all year becomes a PDF with one command — Docs as code.