Re: Is there a need for a hard copy OpenBSD documentation project?

[Luke Seubert <lseubert@radix.net>]

STeve Andre' on 09/01/2000 9:52 PM scribbled:

> I hear the soft muffled screams of innocent trees...
> 
Oh no!  Guilt trip!  Well, one could always use recycled paper :-)

> I don't think it would be a good idea to do this.  There are times, yes, when
> it's nice to have a piece of documentation in paper form--I did that with the
> ppp doc so I could really understand it.  But in a year+ of OpenBSD usage
> it is the only thing besides the FAQ that I have printed out.
> 
Yes, that ppp doc would be handy - that is one *long* man page!  I accept
that for you, little or no hard copy is a fine solution.  I hope more
responses roll in and some sort of consensus develops one way or the other.
(Oh how pathetically naive I am ;-)

However, other folks might really like having full hard copy documentation -
something they can take home from work over the weekend to study.  Newbies
who don't even know what commands they can access through man or apropos
would benefit greatly from having it all laid out in front of them. And
having complete and thorough hard copy documentation for software is an
extra mark of quality, stability, and the highest professionalism.

> The more realistic problem here is that this project is an ongoing target with
> the associated doc changes, such that what was printed today is going to
> look stale in a year.
> 
> Unless you are pouring over ALL the docs, how many are you apt to  look at
> before they are outdated?
> 
This is an excellent point  - how in the world to keep the documentation up
to date?  OpenBSD has a pretty aggressive release schedule!

Here is a potential solution to the problem of keeping hard copy
documentation up to date.  Please chew it over and kick back a critique.

First off, throw away the idea of a conventional hardback or paperback book.
Any book would be out of date before it finally rolled off the printing
presses.  A book methodology using traditional publishing industry
techniques for creating hard copy documentation for OpenBSD just won't work,
IMHO.

Instead, think of all the docs placed inside of a quality three ring binder.
With a three ring binder, pages can be easily inserted and removed in order
to keep things current. Imagine that all the documentation is arranged in
chapters and sections with a flexible page numbering system and readily
updatable table of contents and index.

Now, let's say that a complete package of documentation is created for
OpenBSD 2.8 and you have purchased your copy of the elegantly prepared
documentation in the three ring binder with a cute logo on the front and all
of that.  Obviously, there will be changes when OpenBSD 2.9 rolls around.
No problem.  You order the documentation update pack for 2.9  When it
arrives, it will contain all the changes made in the documentation between
OpenBSD 2.8 and 2.9.  There would be instructions on what pages in the
binder need to be removed.  And it would have the new pages to be inserted,
along with where they go.  That way, once you purchase a documentation
package, you could keep it up to date with each new release of OpenBSD.

I know this system may sound a bit cumbersome or strange, but I have seen it
work in real life.  I have "The Modern Electronics Manual" put out by
Wimborne Publishing Ltd from Great Britain.  (I dabble in some electronics
as a hobby, and this manual is an excellent reference and learning tool.)

Anyway, this manual is largely static.  I mean really, there are no new
radical changes being made to Ohm's Law - so that section never gets
updated.  Most of the OpenBSD system is probably the same.  Certain parts of
it don't change, or change very slowly over time.

However, in the electronics field, there are new developments coming along
all the time.  Wimborne documents these changes, and then offers update
packs for those who want to keep up with the cutting edge.  One simply
removes the outdated pages, and inserts the updated pages and presto!
Current documentation up to date in a rapidly evolving field.

An OpenBSD manual could use the same sort of procedure to keep up with the
changes of each release.

Does this sound like a workable solution?

> Best to leave the very good OpenBSD documentation in cyberspace, and a
> few more trees in the forest.
> 
> --STeve Andre'
> 
You may be right Steve.  But maybe enough people will like this idea, and
some clever solutions to the updating problem will be worked out.  It might
be worthwhile to do.  Well, we'll see.

Thanks for contributing your thoughts.

--

Luke Seubert


"If you have an apple and I have an apple and we exchange apples then you
and I will still each have one apple. But if you have an idea and I have an
idea and we exchange these ideas, then each of us will have two ideas."

  - George Bernard Shaw