<story><title>Why is the OpenBSD documentation so good?</title><url>https://dataswamp.org/~solene/2022-08-18-why-openbsd-documentation-is-good.html</url></story><parent_chain></parent_chain><comment><author>wolfgang42</author><text>My perspective is skewed since I only get the questions that the documentation &lt;i&gt;doesn’t&lt;/i&gt; answer, but I support someone who uses OpenBSD and the documentation is far from perfect. Some complaints that spring immediately to mind:&lt;p&gt;The man pages sometimes document things only by implication, or with confusing wording, such that if you already &lt;i&gt;know&lt;/i&gt; 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.)&lt;p&gt;From what I can figure out, their &amp;#x27;ksh&amp;#x27; 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&amp;#x2F;07&amp;#x2F;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.&lt;p&gt;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.)&lt;p&gt;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.&lt;p&gt;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.</text></comment>
<story><title>Why is the OpenBSD documentation so good?</title><url>https://dataswamp.org/~solene/2022-08-18-why-openbsd-documentation-is-good.html</url></story><parent_chain></parent_chain><comment><author>anyfoo</author><text>It really, really is.&lt;p&gt;The comprehensive and well-written man-pages are one of the reasons why OpenBSD feels so &amp;quot;complete&amp;quot;. In German, you&amp;#x27;d say &amp;quot;aus einem Guss&amp;quot;, which almost literally translated means &amp;quot;from a single mold&amp;quot;.&lt;p&gt;Linux often feels like a bunch of different things thrown together (which it always was), and the quality, or even just existence, of the documentation differs accordingly.</text></comment>