From owner-freebsd-doc  Tue Jul 18 11:36:37 1995
Return-Path: doc-owner
Received: (from majordom@localhost)
          by freefall.cdrom.com (8.6.10/8.6.6) id LAA04170
          for doc-outgoing; Tue, 18 Jul 1995 11:36:37 -0700
Received: from grendel.csc.smith.edu ([131.229.222.23])
          by freefall.cdrom.com (8.6.10/8.6.6) with ESMTP id LAA04150
          for <doc@freebsd.org>; Tue, 18 Jul 1995 11:36:35 -0700
Received: from localhost (jfieber@localhost) by grendel.csc.smith.edu (8.6.5/8.6.5) id OAA15698; Tue, 18 Jul 1995 14:37:47 -0400
From: jfieber@grendel.csc.smith.edu (John Fieber)
Message-Id: <199507181837.OAA15698@grendel.csc.smith.edu>
Subject: Re: Documentation
To: bsletten@vivid.autometric.com
Date: Tue, 18 Jul 1995 14:37:47 -0400 (EDT)
Cc: doc@freebsd.org
In-Reply-To: <9507181222.ZM29598@jester.autometric.com> from "Brian Sletten" at Jul 18, 95 12:22:02 pm
Content-Type: text
Content-Length: 2302      
Sender: doc-owner@freebsd.org
Precedence: bulk

[cc'd to doc@freebsd.org, I hope you don't mind...]

Brian J. Sletten <bsletten@autometric.com>
> Hi, John. Jonathan Bresler pointed me to you as the documentation
> meister. As you may have heard, the DC FreeBSD group wants to
> help out with documentation.  I was wondering if you could let me
> know what exists, what is needed, and where the central
> repository might exist.

Lets see....

Yes, a repository exists in freebsd-current.  In particular,
/usr/src/share/doc/faq and /usr/src/share/doc/handbook.  Both
documents are tagged according to the linuxdoc DTD (sgml) and can
be converted to other formats using the sgmlfmt(1) command.

I'm not the direct maintainer of the FAQ, but will comment that
it needs a MAJOR overhaul.  The handbook is my bag of worms.

What is needed for the handbook is:

1) Extensive proofreading and correction.
2) New material

For the first option, many statements need to be checked against
reality.  Cross references need to be placed.  Grammer needs to
be formalized and normalized.  Many sections are obviously
unedited documents that formerly stood on their own and they need
to be "edited in" such that redundant material is replaced with
cross references to the appropriate sections.  

For new material, sections mared with * need to be written!
I have a couple in-progress, namely kernel config and
adding/configuring disks.  I also have a submitted section on
DES/MD5 but it needs some editing before going in.

Also, don't feel restricted to the "table-of-contents" that
currently exists.  In particular, I'm thinking of a bit of
restructuring that would create a "basic system administration"
part, followed by an "ISP guide" covering the things ISP types
need/want to know about setting up services.  

For people unfamiliar with SGML, I'm perfectly happy to accept
plain text or LaTeX.

Finally, on the WWW side of things, I'd like to see a home page
for the user groups!  I'd rather not maintain them myself, but
I'll certainly provide a directory page with hints about starting
a group.  If the group members cannot supply a home machine for
their pages, I'm shure it could be arranged to make an account on
www.freebsd.org so someone could maintain a page there.

-john

=== jfieber@cs.smith.edu ========== Come up and be a kite!  --K. Bush ===