free counter
Tech

How come the OpenBSD documentation so excellent?

Compiled by Solne, on 18 August 2022.

Tags: #openbsd#documentation

The OpenBSD operating-system may be secure, also for having a precise and excellent documentation. In this text, I’ll make an effort to figure out why is the OpenBSD documentation so excellent.

The OpenBSD project website

This is a set of supports used to distribute information:

  • first email upon installation
  • man pages
  • website
  • FAQS on the site
  • Examples
  • Newsletters for announcement

Let’s study them one at a time.

The initial email

Once you installed OpenBSD, once you sign in as root for the very first time, you’re greeted by way of a message saying you received a contact. In fact, there’s a contact from Theo De Raadt crafted at install time which welcomes one to OpenBSD. It offers you several hints about how exactly to begin with, but especially it leads one to the afterboot(8) man page.

The afterboot(8) man page is referred to as “what to check following the first complete boot”, it’ll expose you to the most typical changes you might want to do on your own system. But most of all, it explains how exactly to utilize the man page like considering the SEE ALSO section resulting in other man pages linked to the existing one.

The afterboot(8) man page

Man pages

The person pages certainly are a solution to ship documentation with a software, usually you discover a guy page with exactly the same name because the command or configuration file you would like to document. It appears man pages appeared in 1971, the “man” means manual.

Wikipedia page concerning the man page

The manual pages are literally the core of the OpenBSD documentation, they follow some standard possesses much metadata inside it. Once you write a guy page, you not merely write text, nevertheless, you describe your text. For example, when we have to make reference to another man page, we shall utilize the tag “cross-reference”, this rich format allows accurate rendering but additionally accurate searches.

Whenever we refer at a full page in a text discussion, we often write their name like the section, like man(1). In the event that you see man(1), you realize it is a man page for “man” within the initial section. You can find 9 parts of man pages, that is an old solution to sort them into categories, so if a couple of things have exactly the same name, you utilize the section to distinguishes them. Here’s a good example, “man passwd” will display passwd(1), that is a program to improve the password of a user, nevertheless, you could desire to read passwd(5) which describes the format of the file /etc/passwd, in cases like this you’ll use “man 5 passwd”. I usually found in this manner of discussing man pages very practical.

On OpenBSD, you can find man pages for all your base systems programs, and all of the configuration files. We always play the role of very consistent in the manner information is shown, and the wording is carefully chosen to be as clear as you possibly can. They are a standard effort involving multiple reviewers, changes should be approved by a minumum of one person in the team. When an OpenBSD program is modified, the person page should be updated accordingly. The pages may also be occasionally updated to add more history explaining the origins of the commands, it certainly is very instructive.

With regards to packages, there is absolutely no guarantee once we just bundle upstream software, they could not give a man page. However, packages maintainers supplies a “pkg-readme” apply for packages requiring very specific tuning, theses files are available in /usr/local/share/doc/pkg-readmes/.

Online OpenBSD man pages reader: the rich format shines here

Website

One method to distribute information linked to OpenBSD may be the website, it explains what the project is approximately, which hardware it is possible to set it up, why it exists and what it offers. It includes a large amount of information which are interesting before you install OpenBSD, so that they can not be in a guy pages.

The OpenBSD website

FAQ

I find the treat the FAQS area of the website as another support for documentation. It is a special place which has real life use cases, as the man pages will be the reference for programs or configuration, they lack the picture as a whole overview like “how exactly to achieve XY on OpenBSD”. The FAQ is specially well crafted, it has different categories such as for example multimedia, virtualization and VPNs…

The OpenBSD FAQ

Examples

The OpenBSD installation includes a directory /etc/examples/ providing configuration file samples and comments. They’re a sensible way to get started doing a configuration file and understand the extendable described in the according man page.

Announcements by email

Documentation can be keeping the users informed about important news. OpenBSD is utilizing an opt-in method with the e-mail lists. One list that’s very important to information is announce@openbsd.org, news releases and erratas are published here. It is a simple and reliable method doing work for everyone having a contact.

No wiki

That is a significant point for me, all of the OpenBSD documentation is stored in the sources trees, they need to be committed by someone with a commit access. Wiki frequently have orphan pages, outdated information, duplicates pages with contrary content. While they could be rich and useful, their content often have a tendency to rot if the city doesn’t spend an enormous time and energy to maintain them.

One system all together

Finally, the majority of the above can be done because OpenBSD is produced by exactly the same team. The team can enforce their documentation requirements throughout, which result in accurate and consistent documentation all over the system. That is more difficult on a Linux system where all components result from various teams with different methods.

Once you obtain OpenBSD, you need to be in a position to learn how to use all of the components from the bottom system (= not the packages) with just the person pages, being offline doesn’t prevent one to configure one’s body.

Why is an excellent documentation? It’s hard to inform. For me, having a trustful way to obtain knowledge may be the most important, regardless of the format or support. If you cannot trust everything you read since it could be outdated, or not applying on your own current version, it’s difficult to rely on it. Man pages certainly are a good format, very practical, but only once they are well crafted, but it is a trial requiring considerable time.

Read More

Related Articles

Leave a Reply

Your email address will not be published.

Back to top button

Adblock Detected

Please consider supporting us by disabling your ad blocker