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. | |
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. | |
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. | |
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/. | |
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. | |
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... | |
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 [email protected], 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. |