Date: Sun, 7 Apr 2002 01:17:09 +0300 From: Giorgos Keramidas <keramida@freebsd.org> To: Murray Stokely <murray@freebsd.org> Cc: freebsd-doc@freebsd.org Subject: Splitting the Handbook? (was: [a couple of new doc PRs]) Message-ID: <20020406221709.GA1181@hades.hell.gr> In-Reply-To: <20020404062954.6607E2E827@mail.freebsdmall.com> References: <20020404062954.6607E2E827@mail.freebsdmall.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--7JfCtLOvnd9MIVvH
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
On 2002-04-03 22:29, Murray Stokely wrote:
> We only include 1 paragraph on MUAs in the mail chapter of the FreeBSD
> Handbook. This is very valuable information that new users need. We
> should add at least 5 pages talking about installation and usage of
> Mutt, Pine, fetchmail, the concepts of local Unix mailboxes vs POP3 /
> IMAP. Available IMAP clients for FreeBSD. Pointer to the SSH
> tunnelling section for these insecure protocols, etc..
On 2002-04-03 22:57, Murray Stokely wrote:
> Chapter 18 of the Handbook only covers sendmail. Changes were
> recently made to rc.conf to make it easier to install and use
> alternative MTAs. We should document this configuration setting, and
> describe the process of setting up Postfix and qmail to be the default
> system MTA.
I've putting a lot of thought, since a few months ago, to something that
might sound nice regarding this and other things about our documentation
set. Right now, we have the Handbook, which is a great tome of knowledge,
split in parts, chapters, sections, subsections and so long and so forth.
This is hard to search though. It's difficult for a newcomer to find his
way around in this huge document. It is time, I think to separate the
Handbook in smaller parts. The main thing that I was thinking about is how
would one go about separating these parts. Putting related items together
seems like a nice thing, so we shouldn't make the users dig in dozens of
books to find all there is to know about using FreeBSD as (say) a dialup
PPP gateway, a firewall, and a mail, web, whatever proxy.
These two PRs, recently opened would be easy to handle if we had a
collection of FreeBSD books, targeted to specific "functionality" aspects
of FreeBSD. This is what helps in clearly separating the topics that each
book or book collection will be about too. What are FreeBSD machines used
for today?
- Server machines.
- Workstations.
- (Both, but this can clearly be covered in the previous parts.)
So, we need two book collections. One that talks about the administration
of a FreeBSD server, and one that talks about using FreeBSD as a
workstation for every day jobs. Right now, these two topics are covered in
a variety of places, with some things being explained in the Handbook,
other less important (?) or complicated things explained in articles, and
yet more explained online at the Web site (for instance, mailings lists,
subscriptions, unsubscriptions, etc.). By noting this, I do not mean to
say that the existing documentation is not useful, or not organized, or
that we should just throw it away. It represents the experience and work
of dozens of contributors and developers, and the result of thousands of
man hours of work.
But what can we hope to achieve by splitting the documentation in
server/workstation categories? Well, for one thing, PRs like the two
quoted above will have an easy to spot place in the lot. We make a couple
of new books titled "Internet Mail". The book that is part of the "System
Administrator's Bookshelf" talks about MTAs, the default MTA of FreeBSD (in
this case Sendmail), then alternative MTAs, their installation and
configuration, about system-wide virus protection, POP or IMAP protocols,
and software that needs to be installed to make them available to
end-users, and other stuff that a system administrator needs to know about
Internet Mail. The Internet Mail book that is part of the "FreeBSD User's
Bookshelf" mentions that an MTA needs to be installed and configured by the
system administrator, points to the "System Administrators's Bookshelf" for
more details, and goes on to talk about MUA's like Mutt and Pine, about
programs like fetchmail, procmail, or maildrop, and other things that an
end-user will be interested to know regarding Internet Mail usage in his
every day work.
Something like this can not and will certainly not happen during a night
time's hacking session. If it looks like a nice long-term goal though,
perhaps we need to start splitting things off the Handbook. I'm taking
this opportunity of Handbook lacking a detailed explanation of how
Internet mail works, to propose making this a separate book. One
part, two parts (sysadmin & user), it's not really important to have
everything organized and working perfectly right from the beginning.
What is important is, what do you all thing about doing this? I could
start and write a small skeleton for something like this, but before
going crazy about something it's nice to know if it's worth anything,
if I can hope in having your help & assistance in writing those
sections I'm not very good with, or if you'd prefer all this to stay
in the existing Handbook, as a chapter, perhaps two.
/me puts on the flame vest, and
sits down waiting your comments patiently.
Cheers,
Giorgos Keramidas FreeBSD Documentation Project
keramida@{freebsd.org,ceid.upatras.gr} http://www.FreeBSD.org/docproj/
--7JfCtLOvnd9MIVvH
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (FreeBSD)
iD8DBQE8r3Pl1g+UGjGGA7YRArC0AJ0RYzQEYo72oBxFFtJXbhOkKbWA6QCfS/61
6yrtjGK8vZB7Fjim2n8y9mo=
=aDZ0
-----END PGP SIGNATURE-----
--7JfCtLOvnd9MIVvH--
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?20020406221709.GA1181>