My personal thoughts (I'll try to be brief):

 * Is *roff the way to keep on going with documentation?  I gather that
   our macro package is able to generate HTTP with appropriate links,
   which was the biggest objection that I _thought_ that I saw.
   Converting man-pages doesn't sound too productive right now, but what
   about new documents?  Man, as I've said elsewhere, isn't always the
   best mechanism; man assumes that you already know the question to ask,
   which is not always a valid assumption.

   DocType(?) has been suggested; there's also something called Doxygen,
   which is apparently a kind of literate programming tool.  The latter
   could, in principle, help us generate a nice kernel/userland pair
   of volumes.  Any thoughts on these, or is *roff held to be the best
   tool?  (A principle advantage of *roff is that a fairly basic system
   should have *roff installed anyway, and it can be used with a basic
   line-printer and text console.  Having to install something like 
   TeX or a web-browser---and perhaps needing X up and running---in
   order to read docs is not a healthy requirement.)

 * We have some good information online.  E.g., the web pages have info
   about creating a new device driver and adding system calls.  I can't
   remember seeing these things in _installed_ docs, though.  Are there
   plans to bring this into the standard install with 1.5?  Or is it
   already in 1.4, and I just haven't seen it?

 * There are some USD/PSD(?) (User/Programmer Supplementary Docs) that
   are ``dead references'' in an installed system.  (I.e., a place is held
   for them, but the original docs are missing---presumably they were
   pruned in the process of removing AT&T taint from BSD.)  Ideally, these
   docs should be suitably recreated, and maintained with current document
   formatting tools.  (At least, _I_ think that that would be ideal.
   Others may wish to delete the directories and forget about them.  (^&)

 * Writing new docs is fine, but following up on someone else's comment,
   it's also nice that our docs are fairly current.  The more docs we
   have, the more trouble it is to keep them up to date.  How many
   people have as a major/primary NetBSD commitment the maintaining
   of our documents?

 * There's a guy (who's been a little quite for a while) down in Australia
   who is working on writing a NetBSD book from a beginner's point of
   view.  Just a data point to bear in mind.  (^&  What other books are
   on the horizon?

 * There are people who will burn CD-ROM's at-cost.  How about people that
   will nicely-print system documentation at-cost?  A year ago, I would
   probably have jumped for my check-book if someone had offered to do
   this.  (Now, I have a decent printer.  If people were willing to cover
   the expenses (paper/toner/shipping/wear-and-tear), I would be willing
   to look into setting up something like this from my own system.  Is
   there interest?)

   (This is kind of tangent to the documentation discussion, but bears
   some relation.  *grin*)

 * Related, it takes a little work (I thought) to figure out how to
   typset/print some of our docs.  Perhaps a /usr/share/doc/guide-to-
   the-lost.text file could be written to give an overview of the
   NetBSD documentation and some FAQ's?  There may be a desire to
   just drop in some random help-files, but (IMHO) there should be
   a single, primary guide-to-the-lost.  It might _reference_ some
   random help-files, but should, itself, be a central point of
   reference.  It might be moderately lengthy, but should be well-
   organized and should help beginners get their bearings with
   NetBSD documentation.  Like a leader, it should organize other
   elements, and delegate most of the actual work of documenting
   details.  (^&


Ah well, so much for being brief.  (^&


  "I probably don't know what I'm talking about."  --rkr@rkr.kcnet.com