On Tue, May 17, 2016 at 10:30 AM, Ingo Schwarze <schwa...@usta.de> wrote: > Hi Paul, > > Paul Suh wrote on Tue, May 17, 2016 at 09:20:45AM -0400: > >> I've been playing over at Alpine Linux, to get support for a WiFi card >> that is not supported under OpenBSD. Their installation instructions >> and general documentation are horribly confused and outdated. > > I don't know about the quality of the content of Alpine Linux > documentation. In general, BSD documentation tends to be better > than Linux documentation, so the problem may or may not be specific > to Alpine. > > But Alpine Linux is unique with respect to documentation in more > than one way: It is the first Linux distro that ever used mandoc(1) > by default - since June 2011, more than a year before NetBSD, more > than three years before FreeBSD and illumos. It is the first other > operating system to integrate and enable the OpenBSD man(1) > implementation by default - since December 2014. And as far as i'm > aware, it is still one among the only three systems using OpenBSD > man(1): OpenBSD, Alpine Linux, and Void Linux. > >> Makes me long for our goodness here.
I have experience with Alpine Linux's documentation and I agree completely with the original poster about its low quality. It is frequently quite difficult to find out what you need to know in order to effectively use Alpine. This deficiency is compounded by a developer group that is notably unresponsive to user questions. OpenBSD excels in both areas. It is among the best in this regard, if not the best, of the open-source systems with which I am familiar. I would also comment that the mechanism by which the documentation is delivered is a small issue, in my opinion, compared with the quality of the writing -- how well the document explains the issues that it is attempting to address. I have recently had a look at Rust, an interesting new programming language with which I became aware as a result of someone mentioning it in a post on this list. A significant effort has been made to create a book describing the language. However, in my opinion, the book is not good, failing to adequately explain some of the innovative concepts in Rust. This was not for lack of effort. Perhaps it is simply lack of writing ability on the part of the author (I do not believe it is because he doesn't know his subject). Other factors may be at work, too (the language has been a bit of a moving target). My point is that good documentation is not easy to do, something I think many of us tend to forget. It's also less fun than writing code. Things like K&R that explain their subject so concisely and yet completely take tremendous skill. I myself am in the process of writing a document for a suite of personal financial management tools that I will release on github and I said to my wife the other day that writing the documentation is more difficult than writing the software. /Don Allen > > You are welcome, > Ingo
