Date: Thu, 29 Oct 1998 22:11:06 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: doc@FreeBSD.ORG Subject: RFC: Handbook reorganisation Message-ID: <19981029221106.19143@nothing-going-on.org>
index | next in thread | raw e-mail
[-- Attachment #1 --]
Folks,
What follows is my collected thoughts after staring hard at the Handbook
for the past seven months. I think it's reasonably widely acknowledged that
the Handbook could use some reorganisation (and, eventually, tighter
editing), and this is how I'm (currently) thinking of doing it.
This is long. Sorry about that. There's a lot to cover. If you'd find it
easier to manage, this is also available on the web, at
<URL:http://www.freebsd.org/~nik/hb/comments.txt>;
For reference, the old Handbook structure is listed (to the chapter
level) at
<URL:http://www.freebsd.org/~nik/hb/old-layout.txt>;
Note that this is the Handbook as it was 7 months ago. Some new chapters
or sections have been added here or there, but there haven't been any
major architectural changes in that time.
The layout that I'm proposing will look something like this
<URL:http://www.freebsd.org/~nik/hb/new-layout.txt>;
In some cases this lists down to the section level to make things clearer.
I've attached both these files to this message for the web impaired.
[ Note:
When I'm talking about books, parts, chapters, and sections, I'm using the
terms to mean the DocBook definitions. Briefly, a book is organised as a
hierarchy like so
book
part
chapter
sect1
sectn
chapter
chapter
...
part
chapter
...
Also, the precise ordering of PARTS under this layout is not up for
discussion. By that I mean it's so trivial to change ("Hey, I think
Printing should be number 7, not number 3" ... "OK <tap> <tap> <tap>")
that there's no point in getting bogged down it.
]
Part 1:
Pretty good. Covers how to install FreeBSD (could use expanding, with
screenshots). A basic introduction to Unix, and how to use the ports
system.
"Installing applications" can be split in two -- "Installing from the
ports system" and "Installing a new piece of software by hand". The
latter would talk (briefly) about how to download a typical piece of
software, compile it, and install it.
It does need something at the front that talks about the conventions
adopted in presenting the handbook (i.e., '#' = root prompt, '%' =
user prompt, commands in bold typewriter font, manpages referred to as
command(n), and so on). This is pretty easy to do.
Part 2: System Administration
Rename to "Configuring FreeBSD". This part will talk about how you
configure FreeBSD and *most* of the applications that come with it.
This should not (IMHO) include things like Sendmail or Printing.
Sendmail is really part of the wider application set, and Printing
deserves a part to itself.
Create an overview section that discusses the sort of configuration
knobs that can be tweaked with a FreeBSD installation, and an explanation
of where to find out how to tweak those things.
Break the FreeBSD configuration process into "While the system is
starting", "While the system is running", and "Configuring the FreeBSD
kernel".
Document how to configure the kernel (done) and how to tweak the
boot/run time options (/etc/rc.*, sysctl and so on).
Keep disk quotas in this part.
Move Security out of this part, into both the Applications and Networking
parts. The IPFW discussion belongs in "Internet Communications" and the
Kerberos and S/Key discussions in "Applications".
Part 3: Printing
Based heavily on the existing Printing chapter, and only slightly
reorganised;
Start with an overview chapter.
Then have a "Hardware setup" chapter. This is independent of which
particular spooler you're using.
Then a chapter that talks about LPD. This will consist of most of the
existing Printing chapter.
Placeholder chapters to talk about printing use LPNG and other
alternatives.
Placeholder chapters to talk about Network printing. This may or may
not be necessary, depending on how generic the information about the
LPD spooler is. I'm thinking in particular of things like "Printing to a
Windows NT printer" which isn't covered.
Part 4: Network Communications
Rename to "Serial Communications"
Split up "Serial Communications" and "PPP and SLIP". Create a "Serial
Overview" chapter, and a "Dialling in to remote
hosts/receiving calls" chapter.
These names are misleading. "Serial communications" can, I think,
encompass high speed serial lines (i.e., the thing you'd plug into
the back of a Cisco router), and you might get to a remote host using
methods other than dialling (a hard wired serial line for example).
Perhaps "Before using a modem with FreeBSD" is a better title?
Then a "Using a modem/serial line to talk to remote hosts" chapter?
The title is too wordy.
Part 5: Internet Communication
Create an "Internet Communication" part. Explain the basics of
communicating over the Internet (IP address, gateways, routing,
netmasks, ports). "PPP and SLIP" become two distinct chapters under this
part. Both refer back to the "Before using a modem with FreeBSD" chapter.
Also add a (placeholder) "Ethernet" chapter, for using Ethernet
cards with FreeBSD
Additional chapters to talk about DNS, NFS, NIS, NTP, SMTP, ...
as necessary.
These would talk about the protocols and prerequisites for using them,
but wouldn't deal with their implementation in specific applications.
That's covered in part 5 (i.e., "SMTP" would talk about what it is,
how it relates to the DNS, the ports daemons listen on, the role of
MTAs, MUAs and so forth, but wouldn't actually show anything from
sendmail.cf. . .)
Then pull some of the security information from ealier into this
part in its own chapter (the firewall stuff).
This is not quite right -- logically, information about SAMBA should
sit in here as well. Or do we need a "NetBEUI" part as well to cover
things like that? Or perhaps a couple of chapters, one called
"Networking with Windows" and one called "Networking with Macs" or
similar? But then that's not really a part of "Internet Communications"
which is what this part is about.
Part 6: Applications
Create a (mostly empty) part 5 (part 4 now being "Internet
Communications"). This part contains information about specific
applications. Off the top of my head, "X" (and related topics,
such as window managers and useful X apps), "SMTP servers" (sendmail,
qmail et al), "Web servers" (Apache and others?). Also covers printing,
Kerberos and S/Key.
Should definitely include Quake and Doom :-)
Part 7: Advanced topics
Bring the "Making a port" section up to chapter level. Possibly make
the "Contributing to FreeBSD" chapter a part in its own right.
Create an "Emulation" chapter, and put "Linux Emulation" in there as a
section, with additional section placeholders for SCO. Talk about the
DOS Emulator, and pcemu.
"Booting Diskless" belongs in here I think.
Part 8: Contributing to FreeBSD
Pull "Contributing to FreeBSD" out of "Advanced Topics" and into its
own part (with everything under moving up to chapter level). Under
there, reorganise the structure -- in particular, pull out the
contents from the existing "How to Contribute" section and make them
chapters in their own right. Move the "Source tree guidelines and policies"
and "Adding new Kernel Configuration options" from the old Part 4
("Advanced Topics") to under the "Contributing code" section.
Part 9: Appendices
These should become proper DocBook appendices.
The Bibliography should become a proper DocBook bibliography. It should
also include links to Amazon.com (or Amazon.co.uk) and FreeBSD Inc.
should sign up for the Amazon Associates program to try and get money
for the project.
Obtaining FreeBSD should probably move into Part 1, immediately before
"Installing FreeBSD".
The more I look at this, the more I think that calling the Handbook a single
DocBook 'book' is a mistake. Having it as a 'set' (which can contain
multiple books) would be more useful.
By doing this, everything moves up one level in the hierarchy. All the
<part>s listed above become <book>s, <chapter>s become <part>s and so on.
I think this makes more sense, as the documentation for FreeBSD becomes
a set of books. A book that introduces FreeBSD, a book that talks about
using modems with FreeBSD, a book that talks about Networking (one part
would deal with TCP/IP and the Internet, one part with Windows, one part
with Macs, and so on).
Feedback welcomed. And yes, I am the one planning on donning the magic
hat of handbook editorship, picking up my trusty copy of Emacs (+3 to
manual dexterity, +3d6 to Control spells, but a massively increased
chance of a fumble) and fighting the SGML elements at the end of this
discussion. . .
N
--
C.R.F. Consulting -- we're run to make me richer. . .
[-- Attachment #2 --]
Existing Handbook structure (to <chapter> level)
Part 1:
Introduction
Installing FreeBSD
Unix Basics
Installing Applications: The ports collection
Part 2: System Administration
Configuring the FreeBSD kernel
Security
Printing
Disk Quotas
The X Window system
PC Hardware Compatibilty
Localization
Part 3: Network Communications
Serial Communications
PPP and SLIP
Advanced Networking
Electronic Mail
Part 4: Advanced Topics
The Cutting Edge: FreeBSD-current and FreeBSD-stable
Contributing to FreeBSD
Source Tree Guidelines and Policies
Adding new Kernel Configuration Options
Kernel Debugging
Linux Emulation
FreeBSD Internals
Part 5: Appendices
Obtaining FreeBSD
Bibliography
Resources on the Internet
FreeBSD Project Staff
PGP Keys
[-- Attachment #3 --]
Proposed Handbook structure v1.1 (mostly to <chapter> level, occasionally
to <sectn> level)
Part 1:
Conventions in this documentation (foreward? preface?)
Introduction
Installing FreeBSD
- PC Hardware Compatibility
Unix Basics
Installing Applications:
- Using the ports collection to install applications
- Installing applications by hand
Part 2: Configuring FreeBSD
Overview - What you can configure
While the system is starting
While the system is running
Configuring the FreeBSD kernel
Disk Quotas
Localization
Part 3: Printing
Overview
Hardware setup
The LPD Spooler
...
The LPNG Spooler
...
Printing to Windows NT Printers
Part 4: Serial Communications
Serial Overview
Before using a modem with FreeBSD
Using a modem/serial line to talk to remote hosts
Part 5: Internet Communications
Internet Overview
- IP addresses
- Gateways and routing
PPP
SLIP
Ethernet
SMTP
NFS
NIS
NTP
Security (firewalls)
? Networking with Windows
? Networking with Macs
Part 6: Applications
X
- XFree86 / XiG
- Window Managers
- Useful X applications
Electronic mail (SMTP) servers
- Sendmail
- Qmail
Web servers
...
Part 7: Advanced Topics
The Cutting Edge: FreeBSD-current and FreeBSD-stable
Kernel Debugging
Emulation
- Linux
- SCO
- DOS
- dosemu
- pcemu
FreeBSD Internals
Part 8: Contributing to FreeBSD
Overview
- What is needed?
Bug reports
Documentation
Code
- Source tree guidelines and policies
- Changes to existing code
- New code
Application ports
Hardware/architecture ports
Money, hardware, or Internet access
Donors gallery
Contributors
- Donors Gallery
- Derived Software Contributors
- Additional FreeBSD Contributors
- 386BSD Patch Kit Contributors
Part 9: Appendices
Obtaining FreeBSD
Bibliography
Resources on the Internet
FreeBSD Project Staff
PGP Keys
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981029221106.19143>