Skip site navigation (1)Skip section navigation (2)
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>

next in thread | raw e-mail | index | archive | help

--UQ4RcSpAwQNkOnpT
Content-Type: text/plain; charset=us-ascii

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. . .

--UQ4RcSpAwQNkOnpT
Content-Type: text/plain
Content-Disposition: attachment; filename="old-layout.txt"

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

--UQ4RcSpAwQNkOnpT
Content-Type: text/plain
Content-Disposition: attachment; filename="new-layout.txt"

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

--UQ4RcSpAwQNkOnpT--

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?19981029221106.19143>