Rather than respond to everyone's message individually, I'm going to wrap
them up and respond in this one. This is another long message I'm afraid.
Sean Kelly pointed out that we really need to understand who the taregt
audience are; obviously, the answer is everyone :-)
I'm in broad agreement with Jordan about this. I envisage that the
Handbook (that name is itself probably misleading) needs to cater for
the spectrum of those people who are new to FreeBSD and Unix, through to
people who are very familiar with it, but are looking for information
about something they haven't yet needed to tackle (printing, for example).
I don't think the Handbook should be catering for people for whom FreeBSD
is their first exposure to any operating system. I think we should assume
at least some familiarity with MS-DOS. Not to the batch programming level,
but certainly the understanding that you type commands at the prompt, and
that you need to press RETURN after each command.
This may be less relevant now in the age of Windows. But I think if we aim
at the truly new we'll bite off more than we can chew. If the Handbook is
organised properly, "FreeBSD for the truly new" becomes a chapter that
precedes all the others anyway.
What will probably help is another chapter, "Differences from. . .", with
sections for DOS, Linux, Solaris, SunOS, and any other OS' that people
care to write about.
My suggestions for breaking the Handbook up in to seperate DocBook s
caused some comment. I'm still not sure if this is a good idea or not --
fortunately, once content is organised into chapters it's relatively easy
to use those chapters in different frameworks, so I can experiment with
this without causing undue problems for anyone else. The final decision
on whether or not to do this can wait.
[ 'section' in the following does not indicate a DocBook ]
I think the Handbook can be broadly broken in to two large sections. The
first section deals with the installation of FreeBSD, and getting the user
familiar enough with it that they understand how it's configured (or at
least where the configuration information is held and how to change it)
and how to carry out relatively simple tasks (logging in, editing files,
performing an orderly shutdown, shell scripts).
The second section(s) detail how to carry out specific tasks using FreeBSD
(printing, using a modem, connecting to the Internet) and so on.
In the 'User's guide to the Handbook', users are told "Read the first
section, which gets you up to speed with FreeBSD, and gives you the
grounding you will need to understand the other sections. Then decide
which task you want to carry out (printing, using your modem, connecting
to the Internet) and locate the section that discusses that." The user
then doesn't need to read the Handbook all the way through (in fact, is
probably encouraged not to) but can go straight to those sections that
deal with the task in hand. Only the first few sections have to be read
through from start to finish in order to gain the overall understanding
required.
Occasionally, one of these sections might refer to one of the others. For
example, the beginning of the PPP and SLIP sections would say "Please read
the 'Using a modem with FreeBSD' section before carrying on." The rest of
the PPP and SLIP sections could then assume that the user had correctly
wired up their modem, had used 'tip' to connect to it, issued AT commands
and so forth. That information wouldn't need to be repeated.
I would expect each one of these second sections to conform to a similar
style. Each would start with an overview explaining what that section
covers, and what the user will be able to do when they have completed
working through that section. Pre-requisites will be listed ("You must
have a modem, configured and working (see the "Using a modem with FreeBSD"
section). You must have an account with an Internet Service Provider. You
must have read the previous sections about IP addresses, gateways,
routing,. . .")
The rest of the section 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" section"). 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
parts of the Handbook that could be followed up on.
This is why I think these *might* be better off as seperate books --
I'm familiar with FreeBSD, but have never needed to seriously delve
into the Printing system. As and when I need to attach a printer to my
FreeBSD box, I'd ideally just like to pick up the printing book, read
through it, and do it.
Thinking about this some more, I've made a few more changes to the layout.
"Emulation" is now a part in its own right, and "Kernel debugging" and
"FreeBSD Internals" become part of the "Code" chapter in the "Contributing
to FreeBSD" part. A new part "Staying up to date with FreeBSD" rises from
the flames of "Advanced Topics" (after all, to me, 'Printing' is an
advanced topic -- the term is too nebulous to be meaningful).
I've taken Eivind's suggestion, and pulled Security out into its own Part.
The "Further reading" chapter for this part will include a reference to
the firewall discussion in "Networking" (or perhaps that should be the
other way round?).
The "Configuring" part is really information about how you should go about
configuring FreeBSD, rather than configuring it for a specific purpose.
It's existence is so that other parts can handwave "Add this option to
your kernel" or "Tweak this knob in your startup config file" and have
somewhere to point people who don't know what this means. Of course, this
part would be one of the mandatory "read this before reading on" parts. So
I've pulled out the localisation and disk quota information.
Localisation gets its own part, with chapters for Russian and German (and
French, Spanish, . . .). Disk quotas go in a new "Monitoring and limiting
users" part, which also covers process accounting (thanks to Sean for
mentioning that one) and can talk about things like login.conf as well.
Added "The committers guide" under "Contributing to FreeBSD". This is the
"Welcome to FreeBSD travel. . ." message that new committers get when they
sign up. It's funny, informative, and it might help remove some of the
"FreeBSD committers are a closed group" myth. Incidentally, it's
interesting to see that myth perpetuated at the Halloween MS leaked
document . It's also worth
searching that document and seeing the references to FreeBSD and
code-forking. More specifically, the description of "Open Source
(Apache-style)" sounds more like "Open Source (FreeBSD-style). Where was I?
Oh yes, I was digressing :-)
Rename the "Internet Communications" part to "TCP/IP Networking
(Internet)". Move out most of the additional protocol discussion (SMTP,
NTP, NFS). There's no point having half that information in here and
half in some other chapter talking about the application itself. Instead,
create an "Electronic Mail Servers" part, an "Electronic Mail Clients"
part, a "File sharing" part, and a "Time/date synchronisation part". DNS
is such an integral part of this it starts in this part with its own
chapter. I've left DNS and NIS in here. It's (probably) the wrong place,
but I'm not sure where else to put them.
In "Electronic Mail Servers" split out the content by protocol, with an
overview that explains what these protocols are and how they might be
used. Then detail servers that can be used for these protocols.
"Electronic Mail Clients" talks about MUAs. I think a nice touch would be
to include some information about non-FreeBSD MUAs. The harried SysAdmin
then has information on how to (for example) configure Eudora to fetch
mail from a FreeBSD POP server.
These two parts could be merged into one master "Electronic Mail" part,
with chapters and sections for servers and clients. I'm not sure if this
is a good idea, as you would then need to have two "Overview"s. I think
there should only be one overview per part.
"File sharing" (possibly called "Distributed Filesystems" instead?) talks
about NFS, SMB (Samba), Coda and Appletalk (CAP, NetaTalk).
"Time/date synchronisation" is for NTP. Should anyone have a tutorial on
"How to make your own Stratum 0 time server using FreeBSD", this is where
it would live.
Pull "Contributors" out of "Contributing to FreeBSD" and in to the
Appendices, next to the "FreeBSD Project Staff".
Keep in mind most of these chapters will be empty to start with. I figure
that's not so bad though, because they're (mostly) smaller, it's much
easier when someone comes on the -doc mailing list and says "What can I
do?", they can be pointed at one of these and say "We need volunteers to
write these, please pick one."
Eivind raised the issue of how making the Handbook a series of s
would affect people who want to print it out. It shouldn't, except for
things like page numbers changing.
He makes the (IMHO) more interesting point about how it would affect
people who want to print the Handbook for sale. Apart from giving them
some extra work, it shouldn't. I envisage the Handbook's content being
organised into files along chapter lines, with a master file that uses
HTML entities to reference these chapters. You could have one master file
that organised chapters into one book with many parts, and another that
organises chapters into many books.
What's even more interesting is the notion that people should take the
handbook and sell it. I've been pondering this for a while, but haven't
worked up the energy to kick off a discussion about it.
Large parts of the Handbook are marked (c) the author that wrote them,
with no explicit rights granted except to the Doc. Proj. This could (I
believe) cause problems for anyone that wanted to simply re-print the
Handbook. I'd be happier with a blanket copyright statement for the
Handbook, and responses on file from the authors of particular sections
saying that they assign whichever rights are necessary to FreeBSD Inc.
The Handbook/Doc. Proj. web pages then need updating to mention this
policy on new submissions.
Sean said:
> Again, the goals of the handbook need to be determined. A *hand*book is
> not a set; yet a handbook of, say, 120 printed pages is a good thing to
> have. Maybe what we should be after is a set, but where one of the
> books is a handbook, written for the more experienced or more impatient
> user (with just 10 pages on printing), and then a separate book that
> covers each topic in excruciating detail (with a 100 page book on
> printing). Then FreeBSD would compare well with HP/UX's and Sun's book
> sets.
FWIW, a reasonably recent generation of the RTF version of the Handbook
yielded a 421 page RTF file (!) (at
if you're
interested). I don't think that's a 'handbook', but I think the new
organistion would bring it down into 14 or 15 chunks of 30 pages each
(some a bit more, some a bit less). That sounds more handbook sized to
me.
As to breaking things down for the impatient user, I'm hoping two things
will do that;
1. Organising parts/books with an "Overview" section at the start. The
impatient can probably skip it.
2. Removing a lot of the 'fluff' verbiage. By this I mean the sections
that repeat information about how to (for example) become root, or
how to add a kernel config option.
Sue Blake's comment:
> The first few times I read the Handbook, I read it from cover to cover
> without any idea that some was unnecessary. The "easy" bits were as
> incomprehensible to me as the advanced stuff so it seemed like it all
> had to be conquered before installing.
is hopefully tackled by strongly suggesting that the first few sections
(intro to FreeBSD, installing, how to configure the system) be considered
mandatory, with the other parts/books assuming this level of knowledge.
This gives authors a hint as to the level of knowledge they can assume
from their audience (if it's not in parts 1 or 2 you'll need to explain
it) and only gives us one or two points where the documentation needs to
be more 'newbie friendly' (i.e., the beginning sections).
She also said:
> I'd like to be able to pick up the handbook and instantly find what
> an inexperienced new user needs without much searching, and get that
> only to the level required for now (with links to more info of course)
> and in a sequence that resembles the order in which it can be used.
Hopefully you'll agree that the new structure covers this. As regards
sequence, the user is (past the first 2 parts) free to choose which
sequence they want to read things in -- they should be relatively self
contained. More importantly, they're goal orientated.
And also:
> And the handbook must be readily available in a recognisably
> Microsoft-friendly format if they are to read it before installing, and
> it would be nice if there was some easy way to identify and print just
> the first-needed sections from Microsoft, because that's what people
> will be trying to do with it. (Think about it: col -b is absurd)
RTF is about as MS friendly as it can get. The final output formats for
the Handbook(s) will be
Plain text (7 bit ASCII)
RTF, RTF95 (RTF95 is optimised for Word95, RTF for Word97)
HTML
TeX
PostScript (from TeX)
PDF (from TeX)
Anyway, that's enough for the time being. As always, comments solicited.
The new chapter layout is attached to this message, available from
N