4 ms·

My perspective is skewed since I only get the questions that the documentation doesn’t answer, but I support someone who uses OpenBSD and the documentation is f

My perspective is skewed since I only get the questions that the documentation doesn’t answer, but I support someone who uses OpenBSD and the documentation is far from perfect. Some complaints that spring immediately to mind: The man pages sometimes document things only by implication, or with confusing wording, such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. (To be fair, this affliction is definitely not exclusive to OpenBSD’s manpages.) From what I can figure out, their 'ksh' is a vendored copy that they forked and made a bunch of changes to without ever updating the version string, so despite claiming to be “PD KSH v5.2.14 99/07/13.2” it’s got 20 years of patches added on top and won’t match any ksh you’ll find anywhere else. This is not explained anywhere that I could find. There are some questions in the installer about 802.11 setup which are terse to the point of incomprehensibility and AFAICT entirely undocumented. (I had to go rummaging around in the source code and read the installer script to figure out what it was trying to get me to do.) A particular peeve is that the sh and ksh manpages are completely different, despite documenting the same program. (They’re the same binary, with the non-POSIX bits left out of the sh manpage.) It’s particularly frustrating that there are some things documented well in one but poorly in the other, so once you’ve found the same documentation on both sides you still have to figure out what’s actual differences and what’s just bad phrasing. OpenBSD’s maintainers also seem very insular and their mailing lists have a reputation for being very abrasive, so it’s also very intimidating to propose improvements; as a result these papercuts stick around (not being very obvious to the developers, who already know how these things work and so miss them) and continue to mar the polish.

implements 4y ago
> such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. That was my experience, not being familiar with unix / Linux - but the https://www.openbsd.org/faq/ https://www.openbsd.org/faq/ does go along way to bridge the gap between the man pages and “How can this OS be configured to do what I want?”.
- pasc1878 4y ago
  That is what I find with much Unix and emacs documentation. It is for people who already know the tools, there aren't the hooks whilst you are learning. The documentation I found much better was MS in the 1990s where you git an overview as well as the details. Apple documentation used to be quite good but all their overview docs are now in archive and not updated and you just get the API.
gjadi 4y ago
Don't let the bad rap hinders you. That has not been my (small) experience with the mailing lists. You propose a change: - if it's interesting, you will get advice on how to make it good - if it's good it will get committed - if it's not relevant, you will be told Here are some examples: https://marc.info/?l=openbsd-tech&m=155934125101222&w=2 https://marc.info/?l=openbsd-tech&m=155934125101222&w=2 https://marc.info/?l=openbsd-tech&m=156256473722583&w=2 https://marc.info/?l=openbsd-tech&m=156256473722583&w=2
kuon 4y ago
On the mailing list don't take anything personally and don't try to "feel the room" and you should be fine. Keep it at a pure technical level. It helped me when I had answers that I would have considered rude but where technically correct.
justin66 4y ago
> their mailing lists have a reputation for being very abrasive, so it’s also very intimidating to propose improvement What reaction did you get when you proposed a documentation patch?
- wolfgang42 4y ago
  I’ve suggested this, but the person in question has done enough reading of the mailing lists that I trust their judgement when they say they don’t want to get involved. (Sorry for being so vague here; not being an OpenBSD user myself I don’t really know the details.)
tzs 4y ago
> The man pages sometimes document things only by implication, or with confusing wording, such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. (To be fair, this affliction is definitely not exclusive to OpenBSD’s manpages.) Man pages were not meant to be the only documentation except in the case of simple programs. For everything else man pages were meant to be a concise reference for people who already know how to use the program but needed to jog their memory about some aspect of it. If you needed to learn something complicated, such as sed or awk, you weren't supposed to try to learn from the man pages. You were supposed to reach for your copy of the Unix Programmer's Manual.
- throw10920 4y ago
  ...which is a mistake. There are four kinds of documentation (https://documentation.divio.com/ https://documentation.divio.com/), and splitting up those four kinds up among different places is a very bad decision. Man pages contain at least reference information, but they're very inconsistent about including how-to guides and and explanations, and almost never contain tutorials. Big mistake.
  - disgruntledphd2 4y ago
    I believe that info was meant to fill that niche, but it appears that most non Emacs users have never heard of them.

implements 4y ago

> such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. That was my experience, not being familiar with unix / Linux - but the https://www.openbsd.org/faq/ https://www.openbsd.org/faq/ does go along way to bridge the gap between the man pages and “How can this OS be configured to do what I want?”.

pasc1878 4y ago
That is what I find with much Unix and emacs documentation. It is for people who already know the tools, there aren't the hooks whilst you are learning. The documentation I found much better was MS in the 1990s where you git an overview as well as the details. Apple documentation used to be quite good but all their overview docs are now in archive and not updated and you just get the API.

gjadi 4y ago

Don't let the bad rap hinders you. That has not been my (small) experience with the mailing lists. You propose a change: - if it's interesting, you will get advice on how to make it good - if it's good it will get committed - if it's not relevant, you will be told Here are some examples: https://marc.info/?l=openbsd-tech&m=155934125101222&w=2 https://marc.info/?l=openbsd-tech&m=155934125101222&w=2 https://marc.info/?l=openbsd-tech&m=156256473722583&w=2 https://marc.info/?l=openbsd-tech&m=156256473722583&w=2

kuon 4y ago

On the mailing list don't take anything personally and don't try to "feel the room" and you should be fine. Keep it at a pure technical level. It helped me when I had answers that I would have considered rude but where technically correct.

justin66 4y ago

> their mailing lists have a reputation for being very abrasive, so it’s also very intimidating to propose improvement What reaction did you get when you proposed a documentation patch?

wolfgang42 4y ago
I’ve suggested this, but the person in question has done enough reading of the mailing lists that I trust their judgement when they say they don’t want to get involved. (Sorry for being so vague here; not being an OpenBSD user myself I don’t really know the details.)

tzs 4y ago

> The man pages sometimes document things only by implication, or with confusing wording, such that if you already know the answer it makes sense, but if you don’t it’s near-impossible to find out. (To be fair, this affliction is definitely not exclusive to OpenBSD’s manpages.) Man pages were not meant to be the only documentation except in the case of simple programs. For everything else man pages were meant to be a concise reference for people who already know how to use the program but needed to jog their memory about some aspect of it. If you needed to learn something complicated, such as sed or awk, you weren't supposed to try to learn from the man pages. You were supposed to reach for your copy of the Unix Programmer's Manual.

throw10920 4y ago
...which is a mistake. There are four kinds of documentation (https://documentation.divio.com/ https://documentation.divio.com/), and splitting up those four kinds up among different places is a very bad decision. Man pages contain at least reference information, but they're very inconsistent about including how-to guides and and explanations, and almost never contain tutorials. Big mistake.
- disgruntledphd2 4y ago
  I believe that info was meant to fill that niche, but it appears that most non Emacs users have never heard of them.