Re: The OpenBSD Documentation (FAQ)

[Nick Holland <nick_(_at_)_holland-consulting_(_dot_)_net>]

Mark Farquaad wrote:
...
> 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.

noble goal.  Let's see what you have to say...
...

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

I don't think that this opinion is held by anyone of significance.

We don't want OpenBSD to be difficult to learn.
We want it to attract quality users who make our job more fun.

This does not mean "advanced" users.  This means people who are willing
to say, "I do not know everything, I wish to learn more, and I will work
to learn what I need to learn, I don't expect it to be spoon-fed to me,
I can work my own spoon, thank you".

On the other hand, we don't see our mission is to convert every Windows,
Linux, FreeBSD and NetBSD user to OpenBSD.  We do not see ours as a Holy
Quest to Save the Souls of the Misguided.

I have been involved in educating others in various ways for going on
thirty years now, I have some opinions on how best to teach people. :)

"HOWTO" is just plain wrong.
Teach someone how to ping a node, they know how to ping a node.  Teach
them how ping works, and a few examples on how it could be used, they
will have a tool they may use in ways the teacher never imagined.

A poor teacher will not convey what they know to the student.
An average teacher brings a student to nearly their level.
A good teacher helps the best students far beyond their level.

I'd argue I'm a pretty good teacher, I've seen where some of my students
have gone. :)

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

I would disagree with this statement.  I have never heard this viewpoint
before, either internally or externally to the project.

OpenBSD is well known for security.  It is clear how we achieve this.
Every cracker who has been around a while knows the holy grail is to
find a hole in OpenBSD.  Anyone skilled enough to do this isn't going to
be slowed by obscure documentation, 'specially our "Best Obscure
Documentation in the Business" :).  And for skilled users, our
documentation is not obscure in the least.

> What's to be said about such thinking?

Since I think your premise is wrong, I'm just going to wave my hands
here and say "wrong here, let's see what else you have to say".

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

For the last three or so years, most new content has been written by me.
 Much of what is there predates my involvement in OpenBSD, however.

> 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! :-)))

Well, let's set this straight: Going on somewhere around five years ago,
I was one of those users who was introduced to OpenBSD by the FAQ :).  I
was inspired by some postings on Slashdot, I figured that considering
the amount of hatred being tossed at Theo, he must be on to something,
so I started looking.  Took me about three days to achieve more with
OpenBSD than I had achieved with several years of dabbling with Linux.

The real people who deserve credit and praise for the FAQ are Eric
Jackson,  Wim Vanderputte and Chris Cappuccio, who created the basic
framework now in place (and then basically ran like hell as soon as I
was on the team 8-), and of course, Joel Knight who wrote most of the
(knock-out) PF User's Guide.

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

That's the BSD idea. :)
(granted, you gotta make sure your source is also BSD-compatible!)

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

well...there are several books on OpenBSD that fit this description
precisely...

Hey, if someone wants to do this in a "web-oriented" (i.e., "don't have
to pay for it") way, go for it...

> #2.) People
> Second I feel this project cannot be in the hands and responsibility
> of one guy alone. It's just much too big.

So far, AMEN! :)

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

Ooof.  Sounds like Mozilla or Linux suddenly.

Part of the reason OpenBSD is so different from other open source
projects is the strong leadership of one person, rather than a team or
committee.  You may or may not agree with every direction OpenBSD takes,
but you know for sure what direction that is.  Mob work/rule is a cute
theory, but it doesn't work well, at least for some definitions of
"well".  If you like OpenBSD's vision, keep in mind, it is due to the
leadership of one person: Theo de Raadt, and the fact that people who
(mostly) agree with him are working with him, and people who can't get
over disagreements..uh..don't.

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

Let me tell ya, this is the hardest part of my job: getting people to
look stuff over and tell me if I'm right or not.  Ask one person, you
wait until they are un-busy (which Just Doesn't Happen for skilled
people, I can assure you, and the number of unskilled people on the
project is about zero).  Ask multiple people, you get multiple visions...

The upgrade36.html document is a good example.  Being aware of the
"multiple visions" issue, I asked one person for guidance, he said, "You
have to add X, Y, and Z".  So I did.  Asked a second person, he said (in
a thick Hennglish accent) "WHY DO YOU HAVE X and Z in there?  THAT'S ALL
WRONG!".  *Sigh*.

There is a reason most books have a very small number of authors and a
very small number of editors.  Committees are not where work is actually
done...

> #4.) Distribution
> Of course, free distribution, both as HTML on www.openbsd.org
> and a PDF / txt file on all ftp mirrors.

Which is something of a contraction to your point #1:
 "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,"

If it is on OpenBSD resources, it is an official part of the project,
and it will be supervised and run by OpenBSD developers in their own
way.  Plain and simple.  I'm sure you aren't too interested in donating
space in your house to other people's lives...same basic rule here.
(and if you ARE willing to donate space and power and cooling for around
50 or so computers, let me know. :)

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

and..there are already books...and very good books at that.

Of course, buying a book implies buying...money..something that many
advocates of "free software" are very much against.  Granted, they have
no problem volunteering others to spend time and money, but that's
another rant. :)

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

There's the nightmarish part of the project...
It would be nice to totally restructure the suplimental documentation
(remember: man pages are king.  That's very core to understanding
OpenBSD, anything else on the website is "suplimental").

Unfortunately, doing so would require more time than I have to apply to
the project.  I can maintain what is currently in there, I can add
little things to it here and there, and occasionally, do Something Big
(i.e., new page), but a total re-work is beyond my time abilities now
and probably ever.  I'm a VERY slow writer, and I've already let my time
here eat way too far into my business and income.

I'd love to totally restructure things.  I'd also like to add new
content.  I'd also like to keep things that are currently in there
up-to-date.  My priority list:
  1) Keep stuff up-to-date.  This *MUST* be done.
  2) New content
  3) Restructure

I do ok at keeping stuff up-to-date.  I can not keep up with my new
content ideas.  Restructuring is out of the question while I'm the one
running things.  I wish that wasn't the case.  Its not likely to change
however.

I already spent more time on this than I should, but let me say this:  I
am respectfully doubtful of the ability of a large group of people to
put together an "OpenBSD Documentation Project".  It is not an ego
thing.  I am honored beyond description to be editor and maintainer of
the OpenBSD FAQ, but if someone else comes along and proves they can do
it better, you will find me more than willing to let them take the lead,
and I suspect that Theo would work with them.  But as always, we don't
TALK about these things, we do.  If you want to set up a "better way",
do it, prove you can maintain it, and you might just find we are very
willing to "take it in".  But talk without work is not going to go anywhere.

I had a lot of people tell me "We need better PF documentation".  I had
ONE person who stepped up and made it happen.  That was THE person who
changed things, not all the people telling me what I already knew.

> #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?

For any documentation you write for publication on your own sites, of
course.  Documentation for distribution by the OpenBSD team?  uh, no,
that's for us to decide, and for us to set the criteria for, and as long
as it is our resources, we can be as arbitrary as we chose to be. :)

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

Say, maybe a "Wiki"-style project?  Maybe.

I don't think a Wiki will become part of the OpenBSD project's official
documentation, however, it could be potentially valuable to users, if
properly set up and maintained.  You might even find me contributing to
it. :)

Nick.
-- 
http://www.holland-consulting.net