Author Guide: writing good technical documentation for Linux

Updated November 2026

Good Linux documentation does one job for one kind of reader. It shows commands that work when pasted. It says what success looks like, and it is kept up to date. This guide covers choosing what to write, structuring it, writing clearly, testing it, writing man pages, and getting your work into a project's official docs.

The LDP Author Guide once taught volunteers to write HOWTOs in DocBook for the Linux Documentation Project. Its last revision (2006) is kept by the LDP at tldp.org. This page is independent. It covers writing for any Linux project today, whatever the format. For the toolchains themselves (DocBook, AsciiDoc, Markdown, Sphinx), see the documentation tools mini-HOWTO.

Decide what kind of document

Most confusing documentation mixes different jobs on one page. The Diátaxis framework separates four kinds. It sorts them by whether they guide action or understanding, and whether the reader is learning or working:

The four kinds of documentation (after Diátaxis)
KindReader is…Example
Tutoriallearning by doing"Your first web server in 20 minutes"
How-to guideat work, needs to finish a task"Replace a failed disk in a RAID 1 array"
Referenceat work, needs a facta man page, a list of config options
Explanationlearning, wants to understand"How the page cache works"

A classic Linux HOWTO is usually a how-to guide with a short explanation at the top. Keep long background in a separate section or page, and link to the reference (man pages, project docs) rather than copying it.

Know your reader

Write down, before you start, who will read the page and what they already know. "Can install packages and edit a file with sudo, has never configured NFS" is a useful description. "Linux users" is not. Then:

Structure of a how-to

  1. Title that names the task: "Share a directory over NFS v4", not "NFS notes".
  2. One-paragraph summary: what the reader will have at the end, and the main steps.
  3. Before you start: requirements and warnings (data loss, lock-out risks).
  4. Numbered steps: one action per step, each followed by how to check it worked.
  5. Verify: a final test the reader can run.
  6. Troubleshooting: the three to five errors people actually hit, with the exact message.
  7. Undo or next steps: how to roll back, and where to go next.

Short headings that say what is in a section ("Configure the client") let readers skim and jump. Put the most common case first and the special cases after it.

Write clear sentences

Most current style guides, such as the Google developer documentation style guide, agree on a few rules:

Commands and examples

Examples are the part readers copy, so they must be exact:

Dangerous commands need a warning before them, not after. Anything that formats a disk, rewrites a partition table, flushes a firewall over SSH or deletes data should say so first, and show how to check the target (for example with lsblk).

Write a man page

If your project installs a command, it should install a man page. The man-pages(7) conventions, used by the Linux man-pages project, are a good model.

Sections: 1 user commands, 2 system calls, 3 library functions, 4 special files (/dev), 5 file formats and config files, 6 games, 7 overviews and conventions, 8 system administration commands.

Headings, in this order (use the ones that apply): NAME, LIBRARY (sections 2 and 3), SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, PARAMETERS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, ATTRIBUTES, VERSIONS, STANDARDS, HISTORY, NOTES, CAVEATS, BUGS, EXAMPLES, AUTHORS, REPORTING BUGS, COPYRIGHT, SEE ALSO.

Fonts: bold for literal text the user types (command names, options), italics for arguments the user replaces. A minimal page in the classic man macros:

.TH BACKUPCTL 1 2026-11-04 "backupctl 1.4.0" "User Commands"
.SH NAME
backupctl \- copy a directory to a backup disk
.SH SYNOPSIS
.B backupctl
.RB [ \-n ]
.I source
.I destination
.SH DESCRIPTION
.B backupctl
copies
.I source
to
.I destination
with rsync and keeps the last seven copies.
.SH OPTIONS
.TP
.B \-n
Show what would be copied, but copy nothing.
.SH EXIT STATUS
0 on success, 1 on error.
.SH SEE ALSO
.BR rsync (1)

Preview the file and check it before you ship it:

man -l backupctl.1          # view a local file (man-db)
mandoc -T lint backupctl.1  # report markup problems (package mandoc)

You can also write the page in AsciiDoc or Markdown and generate it with Asciidoctor (-b manpage) or Pandoc (-t man). Install it as /usr/share/man/man1/backupctl.1 (or compressed, backupctl.1.gz) through your build system.

License your documentation

Documentation needs a license, just like code, or others cannot legally fix and redistribute it. Common choices are the code's own license (simplest for docs that ship in the source tree), Creative Commons Attribution-ShareAlike 4.0, and the GNU Free Documentation License. Tag each file with an SPDX identifier, for example SPDX-License-Identifier: CC-BY-SA-4.0 or GFDL-1.3-or-later, the same way as source files (see software release practice). Do not paste text from other documents unless their license allows it, and credit sources you build on.

Contribute to project documentation

The most useful documentation is often a fix to the official docs, because every user of the project then sees it. Each project has its own process. Read its CONTRIBUTING file first. Two examples:

Projects hosted on a forge such as GitLab, Codeberg or GitHub usually take docs changes as merge or pull requests. Start small: a corrected command, a missing package name, a clearer error explanation. Use Git (see Git basics), write a commit message that says why, and answer review comments politely.

Keep it current

Checklist before you publish

Sources