On 2005-09-08 uhel@gmx.net wrote:

> > Kernel config documentation is really high on my wish list
> > and, I guess, a lot of other users...
>
> what kind of documentation do you have in mind?
> The options are described in *man options*. That seems to be the same
> as the link to the FreeBSD handbook but textmode only ;)

  I have been thinking that an interactive documentation reader along with
some additional metainfo in the man pages would allow combining and
limiting the information presented according to somewhat more detailed
context, while keeping the individual manpage as the basic unit of
documentation.  This would allow pulling in basic descriptions of kernel
configuration details from many manpages and also removing text such as
options for other processors.  You could interactively create lists of
various types (such as all network drivers).  For bonus points it could
even include a basic line editor that could assist in creating
configuration files (of all kinds) and able to copy and customize some
types of info from the man pages.  The basic combination and limiting
features would be available from the command line as well, but the
interactive element would allow context to accumulate as you determine it
and to maintain pointers to various pieces of documentation.  This would
also allow better integration of third party documentation that provides
the necessary metainfo (which most wouldn't, but would make it possible).
On the negative side, too much formalism can make it even harder to write
good documentation, so the manipulations would need to be limited to
maintain sanity.

  It seems to me that a major need in documentation that is almost always
inadequate is describing the fundamental relationships of the system.
The ability to create lists and composite descriptions from many manpages
can help with this or in some cases it would be better as a separate man
page.  The idea is man pages that describe relationships generally (and
give documentation and code references) but do not give much detail about
anything, just to put words in relationship to each other for better
overall understanding of the system.  Often times, knowing what man page
to look at is most of the difficulty of solving a problem; documenting
general relationships can provide ideas about what is going on that can
help lead to the needed information.  This is usually a major part of the
information new users need to form a basic understanding of the system
from which the details can be understood.  Also important but difficult to
document are usage intentions, which can help understanding of the
documentation and design even if you want to do things differently.

  The problem with detailed documentation is that it takes more time to
maintain.  It also doesn't take much detail to rival code complexity,
usually without linguistic means as clear as code to describe it.
Additionally, many details of operation are strongly influenced by the
details of C.  IMO, source availability should be used as an advantage and
the use of code references should be increased.  A C manpage that
describes the language purely from a reading code as documentation
perspective would help make this useful to more users.  The interactive
documentation reader might also be able to show code and insert it into
created documentation.

  As an easier goal, the creation of a few composite man pages during the
system build (containing mostly lists with basic descriptions and manpage
references) might be useful.

Matthew Orgass
darkstar@city-net.com