Date: Mon, 5 Apr 1999 23:46:15 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: doc@freebsd.org Subject: Organisation change for the Handbook Message-ID: <19990405234615.B6083@catkin.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
Hi folks,
People seem to be a bit more active on this list recently, so I'm reposting
something from November last year. Now that the DocBook conversion is
done I'm looking at this in more detail, and would appreciate comments.
Sean Kelly, Jordan, Eivind, and Sue Blake[1] will recognise some of this.
Also, this is long, sorry about that.
N
[1] Do you know you've arrived in the FreeBSD project when people just
refer to you by your first name?
=========================================================================
Handbook Reorganisation
The basic idea is simple. The Handbook has grown fairly organically, and
can be reorganised. This reorganisation should reflect how people use the
Handbook, and allow for currently missing content to be slotted in more
easily.
This should also make it easier for projects, such as "FreeBSD Installation
Guide" or the "Programmers Documentation Project" to slip right in to this
framework. If necessary, people can maintain their own books out of the
main FreeBSD doc tree, while still maintaining the FreeBSD look and feel and
integration with the rest of the docs (if they want to, of course).
The Handbook's target audience needs to be understood. The Handbook should
be catering for the spectrum of people who, at one end, have never heard of
Unix or FreeBSD before through to those people who are very familiar with
FreeBSD, but who need a useful reference, or want to know as much as
possible about a topic they haven't yet covered (for example, printing).
This is likely to yield quite a schizophrenic document unless tackled
carefully.
The gist of my proposal is to split the Handbook up in to a number of
smaller books, containing between 70-150 'pages'. These would then truly be
*hand*books. Each book should tackle one topic, and not repeat information
from one of the other books. For example, if a book's topic requires that
the reader reconfigure their kernel (for example, Firewalls), they should be
directed to the appropriate part of the "Configuring FreeBSD" book, instead
of repeating that information there.
A seasoned system administrator will be able to go to whichever book tackles
the task they are trying to complete, without getting bogged down in
extraneous detail. Someone new to FreeBSD will be told "Read these 'x'
books first (which cover installation and configuration) and then go and
read whichever of the other books talk about what you are interested in" to
bring them up to speed.
Note that it should be assumed that the reader has at least some OS
experience. I think it is biting off more than we can chew if we assume we
need to teach OS basics as well (although that could be a topic for another
book in the series, which would give the user enough knowledge to then move
on to some of the others).
Each book conforms to a similar organisation. They begin with an overview
explaining what will be tackled by that book, and what the user will be
able to do when they have completed the book. Any prerequisite knowledge
that the user must have is also outlined here.
The rest of the book then works through whatever that section is talking
about, until the user has done whatever it is they want to do. In general,
if the section requires hardware ("Printing", "Modems", "Ethernet". . .)
then the installation and configuration of that hardware is covered first --
this should cover the physical installation of the hardware ("Plug in your
ethernet card in accordance with the manufacturers instructions") and the
configuration necessary to get FreeBSD to recognise the hardware ("Add the
line "device ..." to your kernel config file and rebuild your kernel. If you
don't know what this means then please read the "Configuring your kernel"
book"). Then the software is covered. In some cases this might include
several different applications. Finally, a "Further reading" section can
cover books, magazines, web sites, and other books in the series.
------------------------------------------------------------------------
Here's how I see the new books shaping up. Note that a lot of the
content doesn't exist yet. My comments are bracketed by '[' and ']'
after each book.
Note that the ordering of books here is *not* implying an order in which
people should be expected to read them.
Book 0: Read This First
Conventions in this documentation (foreward? preface?)
Introduction
Differences from. . .
- DOS
- Linux
- Solaris
- SunOS
- BSDi
- NetBSD
- OpenBSD
Obtaining FreeBSD
Installing FreeBSD
- PC Hardware Compatibility
Unix Basics
[ This is the one that everyone should read first. There's no reason why
the "Installing FreeBSD" and "Unix Basics" chapters couldn't be
separate books in their own right. ]
Book 1: Configuring FreeBSD
Overview
- What you can configure
Making configuration changes
- At boot time (start up)
- At run time
- In the kernel
Further reading
[ If you want to configure FreeBSD then read this. /etc/rc.conf, rc.local,
/usr/local/etc/rc.d/*, how to configure a new kernel, sysctl and other
tunables. This talks about the process, rather than how you would configure
any particular option. Another book might say "Add the foo device to the
kernel", this book explains how to do that. ]
Book 2: Installing Applications
Using the ports collection to install applications
Installing applications by hand
[ Self evident ]
Book 3: Monitoring and limiting users
Overview
login.conf
Disk quotas
Process accounting
Further reading
[ Self evident ]
Book 4: Security
Overview
S/Key
Kerberos
SSH
Further reading
- Firewalls
[ Self evident. Content shamelessly taken from the security section in
the existing Handbook ]
Book 5: The text console
Overview
Syscons
- Virtual terminals
- Fonts
- Using the mouse with syscons
PCVT
Further reading
[ Doesn't currently exist, probably should do. ]
Book 6: Printing
Overview
Hardware setup
The LPD Spooler
...
The LPNG Spooler
...
Printing to printers on other computers
- Windows NT
- Linux
- Macintosh
Further reading
[ Shamelessly taken from existing Handbook ]
Book 7: Using modems and null modems (serial connections)
Overview
Before using a modem with FreeBSD
Using a modem/serial line to talk to remote hosts
Further reading
[ Based on existing content in the Handbook ]
Book 8: TCP/IP Networking (the Internet)
Overview
- IP addresses, netmasks
- Gateways and routing
TCP/IP
- PPP
- SLIP
- Ethernet
DNS
NIS
Security (firewalls)
Further reading
[ A reordering, and an addition to, existing content ]
Book 9: Electronic Mail Servers
Overview
SMTP
- Sendmail
- Qmail
POP
IMAP
Further reading
[ Doesn't currently exist. Would explain the basics of SMTP, what an
MTA does, and how to use the popular ones ]
Book 10: Electronic Mail Clients
Overview
FreeBSD
- Mutt
- Elm
- XFmail
- PINE
Windows
- Eudora
Macintosh
- Eudora
Further reading
[ Doesn't currently exist. This is where the Mutt/Pine/rmail fanatics
get to fight it out with one another. Include chapters explaining how
to configure common MUAs on other platforms to read their mail from
FreeBSD ]
Book 11: File sharing
Overview
NFS
SMB
Coda
Appletalk
Further reading
[ Self evident ]
Book 12: Time/date synchronization
Overview
- NTP
Being a time server
Synchronising from a time server
Synchronising NT to FreeBSD
Synchronising MacOS to FreeBSD
Further reading
[ Self evident ]
Book 13: X11
Overview
XFree86 / XiG
Window Managers
Useful X applications
Further reading
[ Self evident ]
Book 14: Applications
Overview
Mathematica
Doom
Quake
Further reading
[ For those applications that crop up a lot in -questions, or where someone is
motivated enough to write something. Could probably include StarOffice and
Word Perfect in this list as well. ]
Book 15: Staying up to date with FreeBSD
Overview
- Choosing -current?
- Choosing -stable?
Getting the source
- FTP
- CVSup
- CTM
Updating your system ('make world')
Further reading
[ Mostly based on current Handbook content ]
Book 16: Emulation
Overview
Linux
SCO
DOS
- dosemu
- pcemu
Further reading
[ A reorganisation and addition to current content ]
Book 17: Localisation
Overview
Russian
German
Further reading
[ From the existing Handbook ]
Book 18: Contributing to FreeBSD
Overview
- What is needed?
Bug reports
Documentation
Code
- Source tree guidelines and policies
- Changes to existing code
- New code
- FreeBSD Internals
- Kernel debugging
Application ports
Hardware/architecture ports
Money, hardware, or Internet access
The committers guide
[ From the existing Handbook ]
Appendices
Bibliography
Resources on the Internet
FreeBSD Project Staff
Contributors
- Donors Gallery
- Derived Software Contributors
- Additional FreeBSD Contributors
- 386BSD Patch Kit Contributors
PGP Keys
[ This will, I think, be split up. Most of the new books will need their own
biblios, so that section will probably disappear, as will the "Resources on
the Internet" section. PGP Keys might move to "Security" as well. ]
Thanks for reading this far. There are two more books at the back of my mind
that aren't on that list yet.
The first is the "Doc. Proj. primer". If you take a look at
http://www.freebsd.org/~nik/primer/, that's pretty much what I'm expecting one
of these books to look like[1] (in terms of amount of content, level it's aimed
at, and so on).
The second is the Committers Guide. This might be part of the "Contributing
to FreeBSD" book, or it might be one on its own. I'm not sure yet.
Comments welcomed,
N
[1] Yes, I know I've got to commit the primer to the main tree. After not
staring at it for a couple of months I'm rewriting a few bits that are
either confusing or wrong prior to committing. Expect it by the end of
this week.
--
Bagel: The carbohydrate with the hole
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990405234615.B6083>