Re: I am thankful for OpenBSD quality docs

[andrew fabbro]

On Tue, May 17, 2016 at 10:30 AM, Ingo Schwarze  wrote:

> In general, BSD documentation tends to be better
> than Linux documentation


A while back, feeling somewhat bitter after struggling with Linux docs
after growing accustomed to OpenBSD docs, I made this image which
summarizes my feelings:

http://i.imgur.com/EKsD7aG.png

OpenBSD's documentation, in my experience, exceeds the docs provided by
some commercial operating systems, and those companies can afford to have
full-time doc writers on staff.  OpenBSD documentation is the gold standard.

-- 
andrew fabbro
and...@fabbro.org

Re: I am thankful for OpenBSD quality docs

[Paul Suh]

> On May 17, 2016, at 11:17 AM, Donald Allen  wrote:
>
> 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 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,

I would agree with you 100%. I find that for my own software, the release
engineering (including writing and editing docs, taking screenshots, making
sure that the installer works correctly, making sure that the uninstaller
works correctly, testing on multiple systems with multiple configurations,
etc.) takes as much or more time than just writing the software. *Keeping* any
docs up to date (including screenshots and videos) is also a lot of work that
has to be factored in to update releases.


--Paul

[demime 1.01d removed an attachment of type application/pkcs7-signature which 
had a name of smime.p7s]

Re: I am thankful for OpenBSD quality docs

[Donald Allen]

On Tue, May 17, 2016 at 10:30 AM, Ingo Schwarze  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 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

Re: I am thankful for OpenBSD quality docs

[Theo de Raadt]

> 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.

which doesn't help if you have no text to throw at it

Re: I am thankful for OpenBSD quality docs

[Ingo Schwarze]

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.

You are welcome,
  Ingo

I am thankful for OpenBSD quality docs

[Paul Suh]

Folks,

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. Makes me long for our
goodness here.


--Paul

[demime 1.01d removed an attachment of type application/pkcs7-signature which 
had a name of smime.p7s]