This is great. When I was trying to get OpenBSD set up on my RPi, I was expecting a setup doc like this, and was quite disappointed to not find one, considering all I’ve heard about the OpenBSD docs being great. Or maybe I’m mixing up OpenBSD with some other distro… Anyways, I did eventually get OpenBSD working on my RPi but it was not as straightforward as it could have been.
What did you struggle to find? I’m one of the people who’d consider OpenBSD both well documented and straightforward to get into and this makes me curious.
The install instructions are on the release page and on servers/mirrors always right next to the install media. It will also tell you about things like upgrading, as well as a section called “Using online OpenBSD documentation”. If you have a question you can usually find the answer on FAQ on the website.
For background I’ve been a technical writer for ~12 years and very much come from the Every Page Is Page One and Write The Docs traditions of technical writing.
It’s been a few months since my OpenBSD experience so it’s not super fresh in my mind, but I think I can retrace my steps a bit.
I started at the homepage. I was expecting a Get started button or such in the main content but it wasn’t too hard to find the Download link in the sitenav.
Clicking Download takes me to a table of different installation images that I can download. Which one should I download? I actually still don’t know whether I was supposed to download install75.img or miniroot75.img. I was trying to do a minimal, CLI-only setup on my RPi.
At that point I basically had to read all the content on https://www.openbsd.org/faq/faq4.html and figure out what parts are relevant for me, which was maybe 50% of the content on that page. I know that trying to cover all the different hardware/software permutations is a documentation nightmare, but IMO OpenBSD could benefit by creating a few tutorials focused on the most common hardware/software combinations that provide a very gentle and strongly guided explanation of the setup process for that particular combination. Tutorials from Diataxis provides good pointers on how to write a helpful tutorial.
I eventually found the install wizard, which was OK but a lot of the choices weren’t self-obvious for me and took a lot of research to figure out which one is best for me. Ideally, at each step of the setup wizard process, there would be a link explaining that option in-depth and maybe providing pointers on whether a specific hardware/software permutation requires a specific value. Every Page Is Page One has a great quote about supporting decision-making, see below.
Re: FAQs:
If you have a question you can usually find the answer on FAQ on the website.
A lot of technical writers view FAQs as a code smell docs smell. The problem is that the FAQs become an unorganized dumping ground of really important info. Usually a docs set is better off trying to fit that info into a cohesive information architecture (IA). Ideally you have both a cohesive IA and an FAQ that complements it (to account for the fact that some readers would prefer to read traditionally organized docs, while others prefer FAQ-style docs), but the reality is that many docs sites lean too heavy on the FAQs, and the unorganized FAQs become the only place to find really important info.
Every Page Is Page One quote about decision-making support:
Providing the reason and context for acting is really another way of saying, “provide support for decision making… In technical communication, we don’t talk much about decision support; we talk about task support… In many cases, the information people need to complete their tasks is not information on how to operate machines, but information to support their decision making… simply documenting the procedures is never enough… What I am talking about is documenting the context, letting users know what decisions they must make, making them aware of the consequences, and, as far as possible, leading them to resources and references that will assist them in deciding what to do.
They call the documentation on the site “the FAQ” but it’s really not FAQ-style in the disorganized sense some people seem to associate with the term. If you go to the top page:
It’s organized into “Introduction”, “Installation Guide”, etc. And within those sections it’s not even a question and answer format. The “Installation Guide”, which you said you had to read “all the content” on:
strikes me as quite concise. Maybe it’s a matter of different learning styles? I thought the pre-installation checklist provided a good overview of the kinds of decisions that need to be made (similar to what you reference in your quote from “every page is page one.”) and the following sections expand on that and give you the information you need to make those decisions.
Once the system is installed, the man pages are better than any system manual I’ve used in the past 30 years, and the system prompts you to go to the right ones, starting by sending you to afterboot(8). (The rest of the manual is available from there too, if you don’t have the system installed anymore and don’t want to install it just to check out the manual…)
Anyway, I’m not trying to dispute your observations, and I hope it doesn’t sound that way; obviously, the OpenBSD docs that you found did not lead you to a great experience. I’m just pointing out how someone could find them useful enough to say that the docs are “great.”
Yes, we can put aside the FAQ comment. The “OpenBSD FAQ” seems like a well-organized doc set. They really should move away from the FAQ name if the content isn’t even structured as questions and answers.
I think I can sum up the OpenBSD docs situation with this hypothesis. I call it a hypothesis to signal that I haven’t dug into the docs much and don’t have much hands-on OpenBSD experience. Hypothesis: OpenBSD has great guides and references, and possibly explanations, but is lacking in tutorials. That would explain why experienced users love the docs and beginners struggle.
Very important to note that I’m using “tutorials”, “guides”, “references”, and “explanations” in the very specific senses defined at https://diataxis.fr
To reframe the problem: I can never bask in the glory of OpenBSD’s famous man pages if I struggle to install OpenBSD in the first place! Investing more in tutorials that walk you through how to set up OpenBSD on specific hardware/software combinations is probably the most effective way to onboard n00bs like me. OpenBSD will never be able to create a tutorial for every HW/SW permutation so they would have to strategically focus on a subset of common combinations. Or create some kind of template to make it easy for the community members to contribute a tutorial for their HW/SW combination of choice. I would be happy to contribute an RPi4 tutorial for example.
I think the lack of “official” tutorials is an overreaction to some of the deficiencies in the LDP. Back in the late 1990s and early 2000s, Linux was well-noted for a very large pile of “HOWTO” documentation. I think it was initially called just the “HOWTOs” and later became part of the LDP. Those were well noted for being friendly in tone, very easy to follow, notoriously incomplete, frequently incorrect, and generally out of date not very long after they were published, most of them receiving no further maintenance.
Aside: The arch linux wiki is, IMO, a good example of everything those HOWTOs were trying to be but with a channel for correcting them and keeping them maintained.
The OpenBSD project, for a long time, would see new users approach the mailing lists asking for a “HOWTO” on ABC or XYZ without having read the documentation at all, and would see them leave disappointed. Their reaction to this was to attempt to improve the official documentation, incorporate updates to that documentation into their development process, and direct users to that documentation. Sometimes “direct users to that documentation” took a very brusque tone.
(Disclaimer: I’m not affiliated with the project other than being a sometimes-user of it since 1999 or so. These are just recalled observations over that time.)
I can empathize with the struggles. Tutorials suck to maintain. Diataxis sums up the problem perfectly:
You will also often find that no other part of your documentation is subject to revisions the way your tutorials are. Elsewhere in documentation, changes and improvements can generally be made discretely; in tutorials, where the end-to-end learning journey must make sense, they often cascade through the entire story.
And if OpenBSD could not keep theirs up-to-date then I understand the ethos of “better no documentation than incorrect documentation”.
BUT this first-hand experience of struggling through the OpenBSD setup process has really renewed my conviction that tutorials play an important role in the overall docs experience.
Thanks for the convo, I’m sure some OpenBSD maintainers will see our discussion and hopefully it has provided some food-for-thought!
I started at the homepage. I was expecting a Get started button or such in the main content but it wasn’t too hard to find the Download link in the sitenav.
I personally hate “Getting Started” links, but it’s not the phrase or anything, just that my expectation is that it will be non-interesting crap. With I mean with that some is some semi-interactive menu just to get to a download link. And then some usually anyways wrong commands to start something, which feels completely redundant, basically only mentioning things that everyone knows anyways (as in using their own system).
Clicking Download takes me to a table of different installation images that I can download. Which one should I download? I actually still don’t know whether I was supposed to download install75.img or miniroot75.img. I was trying to do a minimal, CLI-only setup on my RPi.
Interesting! I think I always ended up using the release page, which is where you see the mentioned Install Instructions.
At that point I basically had to read all the content on https://www.openbsd.org/faq/faq4.html and figure out what parts are relevant for me, which was maybe 50% of the content on that page. I know that trying to cover all the different hardware/software permutations is a documentation nightmare, but IMO OpenBSD could benefit by creating a few tutorials focused on the most common hardware/software combinations that provide a very gentle and strongly guided explanation of the setup process for that particular combination. Tutorials from Diataxis provides good pointers on how to write a helpful tutorial.
I eventually found the install wizard, which was OK but a lot of the choices weren’t self-obvious for me and took a lot of research to figure out which one is best for me. Ideally, at each step of the setup wizard process, there would be a link explaining that option in-depth and maybe providing pointers on whether a specific hardware/software permutation requires a specific value. Every Page Is Page One has a great quote about supporting decision-making, see below.
To me it always felt like installing windows. Just hit enter all the time until it’s installed.
Re: FAQs:
If you have a question you can usually find the answer on FAQ on the website.
A lot of technical writers view FAQs as a code smell docs smell. The problem is that the FAQs become an unorganized dumping ground of really important info. Usually a docs set is better off trying to fit that info into a cohesive information architecture (IA). Ideally you have both a cohesive IA and an FAQ that complements it (to account for the fact that some readers would prefer to read traditionally organized docs, while others prefer FAQ-style docs), but the reality is that many docs sites lean too heavy on the FAQs, and the unorganized FAQs become the only place to find really important info.
I don’t think that this is true for OpenBSD’s FAQ, even remotely. The OpenBSD FAQ is like the FAQs Newsgroups had or today some Subreddits have. Really nice overview of topics. And then there is man pages which the Install File explains.
I know though that there is many resources where FAQs are the lazy version of “documentation”. Like when people get too annoyed to answer questions or something.
Not an OpenBSD guy myself, but that was really interesting, because I view what OpenBSD does one of the prime examples of doing docs right.
It really bothers me how many people out there are used to horrible documentations, bits the picked up somewhere, especially when that resulted in people having a completely wrong mental concepts.
And I always find it weird when people think docs start and end with installation. That’s really common.
Many years ago I used to write documentation in wikis, forums and blogs only to realize that this is essentially counter-productive. For learning that is. Because it’s not central to the project, it’s likely going out of date, people cannot possibly judge if that documentation is good, idiomatic, correct, etc.
However it is absolutely amazing from a “business” perspective. It’s content for SEO, if it’s hard to find and non-central people will Google, if people ask something on Stack Overflow it will make your project more popular, it will go up in Google Trends, etc. All that you get for crappy documentation that others have to jump in for and miss out if your project has good clear documentation. I hope I don’t advertise doing that now.
Anyways, interesting how the route you take is so important and makes such a difference. Download doesn’t feel like the first thing I click on when I have no idea what I want, but rather the “I don’t care, just let me download it” option. But you are completely right, having the interesting parts hidden at the bottom of the release page is actually pretty odd.
I feel similar about the Go docs by the way. They switched from being clear on the old page to an amalgamation of random things all over the place, with greatly varying quality on the new one. What’s worse is that the good documentation got burried. Same about pkg.go.dev. The old page was easy and quick to browse and while some things got a bit better I hate how to click on everything all the time now. There is a collapsed README, which feels somewhat out of place, so it’s either annoying or you have to click to expand it, you have to click every single type in a package you wanna get an overview in terms of methods, and so on. It’s such a nuisance to browse.
EDIT: Looks like select and reply for quotes messed up. Hopefully formatting is fixed now.
I’m one of the people who’d consider OpenBSD both well documented and straightforward to get into
Wow. Well, I found its learning curve exceptionally steep, myself, and I still find the partitioning tool so fearsomely unfriendly that, for instance, when I reviewed the Thinkpad X13S I never managed to install OpenBSD onto the thing. I couldn’t work out which partitions it wanted where and which were existing, and I was scared I’d nuke the only existing OS on the machine.
OpenBSD is pretty terrible at dual-booting in general.
So far I have tried version 7.1, 7.2 and 7.5. I have given this a fair crack of the whip, and after half a dozen installations, on 7.5 with a lot of work I was able to get it dual-booting on bare metal.
However a subsequent OS reinstallation blew away the bootloader and I have yet to fix that.
Stuff like “how to put it on an existing machine next to an existing OS” is not at all well-covered in the docs, IMHO; nor are things like “here’s how to install a desktop environment.”
Unless I missed it: It only briefly mentions syspatch. It doesn’t cover upgrading software(pkg_add -u) or upgrading to the next released OpenBSD via sysupgrade (or bsd.rd if feeling wild) which happens roughly every 6 months, etc. Note: it’s been a while since I’ve actively ran and maintained OpenBSD, I could be off here with latest best practices).
What about monitoring disk space usage, minor troubleshooting(like logs are here, community forums/chat/etc for more help, etc).
Again, I’m not trying to poo poo the article, I think it’s a great start on getting it installed and useful, but there is more to running an OS than just the setup.
Suggestion: Contact M Carnat, suggest moving it to a wiki, and add that material?
FWIW I have written an article about this howto myself (not yet published – maybe tomorrow), because I thought it was impressive and useful, and while I had comments too, I didn’t think of these things.
Of course others could write successor docs but it’d be good to keep it all in one place.
This is great. When I was trying to get OpenBSD set up on my RPi, I was expecting a setup doc like this, and was quite disappointed to not find one, considering all I’ve heard about the OpenBSD docs being great. Or maybe I’m mixing up OpenBSD with some other distro… Anyways, I did eventually get OpenBSD working on my RPi but it was not as straightforward as it could have been.
What did you struggle to find? I’m one of the people who’d consider OpenBSD both well documented and straightforward to get into and this makes me curious.
The install instructions are on the release page and on servers/mirrors always right next to the install media. It will also tell you about things like upgrading, as well as a section called “Using online OpenBSD documentation”. If you have a question you can usually find the answer on FAQ on the website.
For background I’ve been a technical writer for ~12 years and very much come from the Every Page Is Page One and Write The Docs traditions of technical writing.
It’s been a few months since my OpenBSD experience so it’s not super fresh in my mind, but I think I can retrace my steps a bit.
install75.imgorminiroot75.img. I was trying to do a minimal, CLI-only setup on my RPi.Re: FAQs:
A lot of technical writers view FAQs as a
code smelldocs smell. The problem is that the FAQs become an unorganized dumping ground of really important info. Usually a docs set is better off trying to fit that info into a cohesive information architecture (IA). Ideally you have both a cohesive IA and an FAQ that complements it (to account for the fact that some readers would prefer to read traditionally organized docs, while others prefer FAQ-style docs), but the reality is that many docs sites lean too heavy on the FAQs, and the unorganized FAQs become the only place to find really important info.Every Page Is Page One quote about decision-making support:
They call the documentation on the site “the FAQ” but it’s really not FAQ-style in the disorganized sense some people seem to associate with the term. If you go to the top page:
http://www.openbsd.org/faq/index.html
It’s organized into “Introduction”, “Installation Guide”, etc. And within those sections it’s not even a question and answer format. The “Installation Guide”, which you said you had to read “all the content” on:
http://www.openbsd.org/faq/faq4.html
strikes me as quite concise. Maybe it’s a matter of different learning styles? I thought the pre-installation checklist provided a good overview of the kinds of decisions that need to be made (similar to what you reference in your quote from “every page is page one.”) and the following sections expand on that and give you the information you need to make those decisions.
Once the system is installed, the man pages are better than any system manual I’ve used in the past 30 years, and the system prompts you to go to the right ones, starting by sending you to afterboot(8). (The rest of the manual is available from there too, if you don’t have the system installed anymore and don’t want to install it just to check out the manual…)
Anyway, I’m not trying to dispute your observations, and I hope it doesn’t sound that way; obviously, the OpenBSD docs that you found did not lead you to a great experience. I’m just pointing out how someone could find them useful enough to say that the docs are “great.”
Yes, we can put aside the FAQ comment. The “OpenBSD FAQ” seems like a well-organized doc set. They really should move away from the FAQ name if the content isn’t even structured as questions and answers.
I think I can sum up the OpenBSD docs situation with this hypothesis. I call it a hypothesis to signal that I haven’t dug into the docs much and don’t have much hands-on OpenBSD experience. Hypothesis: OpenBSD has great guides and references, and possibly explanations, but is lacking in tutorials. That would explain why experienced users love the docs and beginners struggle.
Very important to note that I’m using “tutorials”, “guides”, “references”, and “explanations” in the very specific senses defined at https://diataxis.fr
To reframe the problem: I can never bask in the glory of OpenBSD’s famous man pages if I struggle to install OpenBSD in the first place! Investing more in tutorials that walk you through how to set up OpenBSD on specific hardware/software combinations is probably the most effective way to onboard n00bs like me. OpenBSD will never be able to create a tutorial for every HW/SW permutation so they would have to strategically focus on a subset of common combinations. Or create some kind of template to make it easy for the community members to contribute a tutorial for their HW/SW combination of choice. I would be happy to contribute an RPi4 tutorial for example.
I think the lack of “official” tutorials is an overreaction to some of the deficiencies in the LDP. Back in the late 1990s and early 2000s, Linux was well-noted for a very large pile of “HOWTO” documentation. I think it was initially called just the “HOWTOs” and later became part of the LDP. Those were well noted for being friendly in tone, very easy to follow, notoriously incomplete, frequently incorrect, and generally out of date not very long after they were published, most of them receiving no further maintenance.
Aside: The arch linux wiki is, IMO, a good example of everything those HOWTOs were trying to be but with a channel for correcting them and keeping them maintained.
The OpenBSD project, for a long time, would see new users approach the mailing lists asking for a “HOWTO” on ABC or XYZ without having read the documentation at all, and would see them leave disappointed. Their reaction to this was to attempt to improve the official documentation, incorporate updates to that documentation into their development process, and direct users to that documentation. Sometimes “direct users to that documentation” took a very brusque tone.
(Disclaimer: I’m not affiliated with the project other than being a sometimes-user of it since 1999 or so. These are just recalled observations over that time.)
I can empathize with the struggles. Tutorials suck to maintain. Diataxis sums up the problem perfectly:
And if OpenBSD could not keep theirs up-to-date then I understand the ethos of “better no documentation than incorrect documentation”.
BUT this first-hand experience of struggling through the OpenBSD setup process has really renewed my conviction that tutorials play an important role in the overall docs experience.
Thanks for the convo, I’m sure some OpenBSD maintainers will see our discussion and hopefully it has provided some food-for-thought!
I personally hate “Getting Started” links, but it’s not the phrase or anything, just that my expectation is that it will be non-interesting crap. With I mean with that some is some semi-interactive menu just to get to a download link. And then some usually anyways wrong commands to start something, which feels completely redundant, basically only mentioning things that everyone knows anyways (as in using their own system).
Interesting! I think I always ended up using the release page, which is where you see the mentioned Install Instructions.
You’ll find that in the install file. See “Preparing your System for OpenBSD Installation” https://ftp.openbsd.org/pub/OpenBSD/7.5/arm64/INSTALL.arm64
I agree that it is probably not the best place.
To me it always felt like installing windows. Just hit enter all the time until it’s installed.
I don’t think that this is true for OpenBSD’s FAQ, even remotely. The OpenBSD FAQ is like the FAQs Newsgroups had or today some Subreddits have. Really nice overview of topics. And then there is man pages which the Install File explains.
I know though that there is many resources where FAQs are the lazy version of “documentation”. Like when people get too annoyed to answer questions or something.
Not an OpenBSD guy myself, but that was really interesting, because I view what OpenBSD does one of the prime examples of doing docs right.
It really bothers me how many people out there are used to horrible documentations, bits the picked up somewhere, especially when that resulted in people having a completely wrong mental concepts.
And I always find it weird when people think docs start and end with installation. That’s really common.
Many years ago I used to write documentation in wikis, forums and blogs only to realize that this is essentially counter-productive. For learning that is. Because it’s not central to the project, it’s likely going out of date, people cannot possibly judge if that documentation is good, idiomatic, correct, etc.
However it is absolutely amazing from a “business” perspective. It’s content for SEO, if it’s hard to find and non-central people will Google, if people ask something on Stack Overflow it will make your project more popular, it will go up in Google Trends, etc. All that you get for crappy documentation that others have to jump in for and miss out if your project has good clear documentation. I hope I don’t advertise doing that now.
Anyways, interesting how the route you take is so important and makes such a difference. Download doesn’t feel like the first thing I click on when I have no idea what I want, but rather the “I don’t care, just let me download it” option. But you are completely right, having the interesting parts hidden at the bottom of the release page is actually pretty odd.
I feel similar about the Go docs by the way. They switched from being clear on the old page to an amalgamation of random things all over the place, with greatly varying quality on the new one. What’s worse is that the good documentation got burried. Same about pkg.go.dev. The old page was easy and quick to browse and while some things got a bit better I hate how to click on everything all the time now. There is a collapsed README, which feels somewhat out of place, so it’s either annoying or you have to click to expand it, you have to click every single type in a package you wanna get an overview in terms of methods, and so on. It’s such a nuisance to browse.
EDIT: Looks like select and reply for quotes messed up. Hopefully formatting is fixed now.
Wow. Well, I found its learning curve exceptionally steep, myself, and I still find the partitioning tool so fearsomely unfriendly that, for instance, when I reviewed the Thinkpad X13S I never managed to install OpenBSD onto the thing. I couldn’t work out which partitions it wanted where and which were existing, and I was scared I’d nuke the only existing OS on the machine.
OpenBSD is pretty terrible at dual-booting in general.
So far I have tried version 7.1, 7.2 and 7.5. I have given this a fair crack of the whip, and after half a dozen installations, on 7.5 with a lot of work I was able to get it dual-booting on bare metal.
However a subsequent OS reinstallation blew away the bootloader and I have yet to fix that.
Stuff like “how to put it on an existing machine next to an existing OS” is not at all well-covered in the docs, IMHO; nor are things like “here’s how to install a desktop environment.”
Great start! I’d add talking about software updates and any other needed maintenance next.
It does address updating the system. What other rolling maintenance does OpenBSD need, then?
Unless I missed it: It only briefly mentions
syspatch. It doesn’t cover upgrading software(pkg_add -u) or upgrading to the next released OpenBSD viasysupgrade(or bsd.rd if feeling wild) which happens roughly every 6 months, etc. Note: it’s been a while since I’ve actively ran and maintained OpenBSD, I could be off here with latest best practices).What about monitoring disk space usage, minor troubleshooting(like logs are here, community forums/chat/etc for more help, etc).
Again, I’m not trying to poo poo the article, I think it’s a great start on getting it installed and useful, but there is more to running an OS than just the setup.
OK, fair points.
Suggestion: Contact M Carnat, suggest moving it to a wiki, and add that material?
FWIW I have written an article about this howto myself (not yet published – maybe tomorrow), because I thought it was impressive and useful, and while I had comments too, I didn’t think of these things.
Of course others could write successor docs but it’d be good to keep it all in one place.
Sounds totally reasonable!
I agree, I think the article as written is a good, Getting Started guide, as far as getting the OS installed and running.