Title: Why is the OpenBSD documentation so good?
Author: Solène
Date: 18 August 2022
Tags: openbsd documentation
Description: In this article, I'm trying to understand what makes the
OpenBSD documentation that good.
# Introduction
The OpenBSD operating system is known to be secure, but also for having
an accurate and excellent documentation. In this text, I'll try to
figure out what makes the OpenBSD documentation so great.
(HTM) The OpenBSD project website
# A multi medias documentation
Here is a list of supports used to distribute information:
* first email upon installation
* man pages
* website
* Frequently Asked Questions on the website
* Examples
* Commit history
* Newsletters for announcement
Let's study them one by one.
## The first email
After you installed OpenBSD, when you log in as root for the first
time, you are greeted by a message saying you received an email. In
fact, there is an email from Theo De Raadt crafted at install time
which welcomes you to OpenBSD. It gives you a few hints about how to
get started, but most notably it leads you to the afterboot(8) man
page.
The afterboot(8) man page is described as "things to check after the
first complete boot", it will introduce you to the most common changes
you may want to do on your system. But most importantly, it explains
how to use the man page like looking at the SEE ALSO section leading to
other man pages related to the current one.
(HTM) The afterboot(8) man page
## Man pages
The man pages are a way to ship documentation with a software, usually
you find a man page with the same name as the command or configuration
file you want to document. It seems man pages appeared in 1971, the
"man" stands for manual.
(HTM) Wikipedia page about the man page
The manual pages are literally the core of the OpenBSD documentation,
they follow some standard and contains much metadata in it. When you
write a man page, you not only write text, but you describe your text.
For instance, when we need to refer to another man page, we will use
the tag "cross-reference", this rich format allows accurate rendering
but also accurate searches.
When we refer at a page in a text discussion, we often write their name
including the section, like man(1). If you see man(1), you understand
it's a man page for "man" within the first section. There are 9
sections of man pages, this is an old way to sort them into categories,
so if two things have the same name, you use the section to
distinguishes them. Here is an example, "man passwd" will display
passwd(1), which is a program to change the password of a user, however
you could want to read passwd(5) which describes the format of the file
/etc/passwd, in this case you would use "man 5 passwd". I always found
this way of referring to man pages very practical.
On OpenBSD, there are man pages for all the base systems programs, and
all the configuration files. We always try to be very consistent in
the way information is shown, and the wording is carefully chosen to be
as clear as possible. They are a common effort involving multiple
reviewers, changes must be approved by at least one member of the team.
When an OpenBSD program is modified, the man page must be updated
accordingly. The pages are also occasionally updated to include more
history explaining the origins of the commands, it's always very
instructive.
When it comes to packages, there is no guarantee as we just bundle
upstream software, they may not provide a man page. However, packages
maintainers offers a "pkg-readme" file for packages requiring very
specific tuning, theses files can be found in
/usr/local/share/doc/pkg-readmes/.
(HTM) Online OpenBSD man pages reader: the rich format shines here
## Website
One way to distribute information related to OpenBSD is the website, it
explains what the project is about, on which hardware you can install
it, why it exists and what it provides. It has a lot of information
which are interesting before you install OpenBSD, so they can't be in a
man pages.
(HTM) The OpenBSD website
## FAQ
I chose the treat the Frequently Asked Questions part of the website as
a different support for documentation. It's a special place that
contains real world use cases, while the man pages are the reference
for programs or configuration, they lack the big picture overview like
"how to achieve XY on OpenBSD". The FAQ is particularly well crafted,
it has different categories such as multimedia, virtualization and
VPNs...
(HTM) The OpenBSD FAQ
## Examples
The OpenBSD installation comes with a directory /etc/examples/
providing configuration file samples and comments. They are a good way
to get started with a configuration file and understand the file format
described in the according man page.
## Commits history
This part is not for end users, but for contributors. When a change is
done in the sources, there is often a great commit message explaining
the logic of the code and the reasons for the changes. I say often
because some trivial changes doesn't require such explanations every
time. The commit messages are a valuable source of information when
you need to know more about a component.
## Announcements by email
Documentation is also keeping the users informed about important news.
OpenBSD is using an opt-in method with the mailing lists. One list
that is important for information is announce@openbsd.org, news
releases and erratas are published here. This is a simple and reliable
method working for everyone having an email.
## No wiki
This is an important point in my opinion, all the OpenBSD documentation
is stored in the sources trees, they must be committed by someone with
a commit access. Wiki often have orphan pages, outdated information,
duplicates pages with contrary content. While they can be rich and
useful, their content often tend to rot if the community doesn't spend
a huge time to maintain them.
## One system as a whole
Finally, most of the above is possible because OpenBSD is developed by
the same team. The team can enforce their documentation requirements
from top to bottom, which lead to accurate and consistent documentation
all across the system. This is more complicated on a Linux system
where all components come from various teams with different methods.
When you get your hands on OpenBSD, you should be able to understand
how to use all the components from the base system (= not the packages)
with just the man pages, being offline doesn't prevent you to configure
your system.
# Conclusion
What makes a good documentation? It's hard to tell. In my opinion,
having a trustful source of knowledge is the most important, whatever
the format or support. If you can't trust what you read because it may
be outdated, or not applying on your current version, it's hard to rely
on it. Man pages are a good format, very practical, but only when they
are well written, but this is a difficult task requiring a lot of time.