The OpenBSD Documentation (FAQ)

[Mark Farquaad <markfarquaad_(_at_)_gmail_(_dot_)_com>]

Hello everyone,

O.K., I've put quite some thought into this, but I'll *try*
to be shorter than in my last post:
(Afterthought: Not much luck I guess... )

I would like to see an improvement or re-organization of
the OpenBSD documentation on the "user level". And I'm
willing to put some effort, time (and blood ;) into this myself.


Index of this post ;-)))))))):
- Abstract
- Security by fewer users
- The current FAQ
- My vision / plan for the future OpenBSD Documentation
- Merging / transmogrifying / mutating old FAQ to new Documentation
- Content



Abstract:
---------

OpenBSD is a cool, maybe even the greatest OS out there.
And according to what I've heard, it has by far the most superior 
man pages on any UNIX-like operating system available.
Why is this so?
I've been told for very good reasons: Every developer who submits 
some code or new functions / features, must also submit a full 
description of it in quality readable and understandable english 
man pages.
The text of these man pages is quality-checked by the other devs at 
time of submittance via CVS, and failing to submit good quality 
documentation results in failure of acceptance of the submitted 
code. (Or something like this.)
A great system: It insures the quality of man pages, which are 
essential for the development of further safe and reliable code 
/ functions / features.

The OpenBSD developer team (and "us" users) have all reason to be
proud of the great documentation in the man pages of OpenBSD.
It's great.

I, as a rather new user of OpenBSD couldn't be further away
from wanting to change anything about that. Quite the contrary:
I'd like to bring that same quality style of documentation to the
user-level, to people like me, to people who are *not* devs,
to people who might install OpenBSD or some of its applications
for the first time.

As we all know, the benefits of quality documentation are:
1.) Security by knowing what works how.
2.) Freeing up personal time of individuals which is otherwise 
uselessly wasted and needed to learn a poorly documented 
functions / features. This individual time then is available for 
better things, such as further improving the code or any other 
part of OpenBSD (or learning about OpenBSD).

I think it's fair to say, that users of OpenBSD could greatly benefit
from an extensive, up-to-date and good quality "user" documentation.
And who knows, someday they might be more than just users.
And the less frustration they had with OpenBSD, the more they 
might be willing to become a part of an effort to actually submit
work on OpenBSD.



Security by fewer users:
------------------------

I know that some people here probably feel it is GOOD that
OpenBSD is hard to learn, some people here probably feel it
should be even harder, or at least not easier to learn how to
use OpenBSD, than when they did.
Why?
The thinking behind it is, I fear (and I don't share that view), 
that the fewer "newbies" are attracted to OpenBSD, the smaller
the OpenBSD community, the fewer web servers, firewalls and
desktop systems out there will be running with OpenBSD 
AND THE FEWER CRACKERS / SKRIPT KIDDIES will find
it worthwhile trying to find out how to crack OpenBSD systems.
This thinking is like: "I don't want others to use it because they 
might attract crackers who could become dangerous to me too."


What's to be said about such thinking?

#1.) This is not the way of the (open) source ;), 
thus destined to fail. OpenBSD is an open source project.
Once you start withholding information, not sharing information,
even from complete beginners, just because of a (assumed) personal 
benefit, you are not far away from making the source code secret 
and becoming Microsoft. (The power of the dark side...)

#2.) Theo de Raadt is specifically holding regular audits at his 
house (I read this), where he invites hacker friends to try to hack
and break into OpenBSD.
OpenBSD takes a proactive stance towards security, takes 
action to find and eliminate security issues before they are
discovered by crackers.
I say bring it on: If ten times more crackers / script kiddies than 
today can find a security hole in a newbie's OpenBSD installation, 
and they can use this exact same security hole to get into YOUR 
OpenBSD system, either YOU have something very poorly 
configured (like a newbie), or OpenBSD is not as good as it 
should / would like to be.
I trust the developers of OpenBSD that their stuff is good.
It's another form of respect if you will. Not wanting to share 
OpenBSD with more people is the contrary (I feel).



The current FAQ:
----------------

Wanting to improve the user-level documentation doesn't mean 
I have a problem with the current FAQ. If I understand correctly, 
it was mainly written and is maintained by Nick Holland.
I'll state it flatly: Without the great current FAQ from Nick Holland
I (and probably quite a few others here) would probably never have
managed to install OpenBSD and become OpenBSD users in the
first place. (Or at least lost many more hairs in the process.)
GREAT JOB! And a 1000 thanks to Nick Holland! :-)))

The current FAQ covers many many very important issues and I'd
be the last to want to throw away or dump any of that already 
existing great work and tremendous effort.

I'm not voting for removing existing work. I'm voting for adding 
more great stuff to it.



My vision / plan for the future OpenBSD Documentation:
------------------------------------------------------

I'm smart ;), but I'm not that smart:
If something great has already been invented, I tend to 
want to copy it rather than re-invent it from scratch.
Same here: I just copy ideas I see elsewhere.

#1.) Organization
First, I feel the user-level documentation should be an 
own, separate ongoing project to make it clear, that the 
devs of OpenBSD have nothing to do with it and are not 
responsible, but that there still is quality control and people 
responsible.

#2.) People
Second I feel this project cannot be in the hands and responsibility
of one guy alone. It's just much too big. It should be open source
and EVERYONE who is willing to put the required effort into
it should be able to contribute some small or big part.

#3.) Quality 
Third, I feel just like the quality control of man pages and even
source code submitted via CVS by developers, any piece / section
of documentation submitted to this documentation project should
be quality controlled. Either by posting to a list or setting up a 
CVS project much like the exiting one for source code and then
voting or something similar weather a new piece of documentation
is good enough to be included.

#4.) Distribution
Of course, free distribution, both as HTML on www.openbsd.org
and a PDF / txt file on all ftp mirrors.
Who knows, once such a project comes to bear fruit, perhaps a 
book can be sold (next to the free pdf version) together with the CD, 
much like it's happening at FreeBSD?

#5.) Layout
I strongly feel the layout should be organized into individual 
chapters, rather than just catch-all collections, to something 
like the not bad at all documentation of either Slackware:

http://www.slackware.com/book/

or FreeBSD:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html

(Yes! Even if OpenBSD *is* better... Take a look beyond the 
perimeter of your chocolate mug and see what others do / have 
done in other fields!)


#6.) Merging / transmogrifying / mutating old FAQ to new Documentation

I imagine, if a new documentation project is set up, we could start
from scratch, deciding what individual chapters need to be present
at first, then just copy, and by doing so, editing or updating the 
current entries of the existing FAQ into the new organized
chapters of the new documentation (should display correctly in 
monotype font):


Documentation Project:                   Existing FAQ:
+--------------------+               +--------------------+
| 1. Installation    |     <----     | How do I install?  |
| 2. Who knows?      |     <----     | How do I ...?      |
|  ...               |               |  ...               |
| 10. PF             |     <----     | How do I PF?       |
+--------------------+               +--------------------+


This approach not only keeps existing valuable material from
the current FAQ, but it also both lets us start with the new project 
right away (important for motivation), but also gives us all the 
time we need to convert and edit the large amount of already 
exiting great material.


#7.) Content

If it's about using OpenBSD, its usable to users, it deserves a place
in the documentation. That's my opinion, that's what documentation
is for. One example is installing and setting up PHP and MySQL
with the chroot of OpenBSD's Apache instance.
If a lot of people want to know about that, why not include it
in the documentation?


Alas, now I tire…

One last note: Instead of having many people simultaneously 
trying to help and posting instructions on their home pages 
(such as how to configure some often needed feature), why not 
bundle those efforts and thus make them all the more worthwhile
for those who are willing to participate in a documentation
project. This doesn't mean there shouldn't be individual home
pages describing and documenting OpenBSD, only those that
say exactly the same or those who don't have their own homepage
but could produce better documentation, those should have the
possibility to contribute in a official documentation project.
Already there are several people I am mailing with who seem
to be willing to help and add lots of *good* content to such
a documentation project.

Greetings,
Mark