From owner-freebsd-doc Sat Apr 6 14:41: 6 2002 Delivered-To: freebsd-doc@freebsd.org Received: from mailsrv.otenet.gr (mailsrv.otenet.gr [195.170.0.5]) by hub.freebsd.org (Postfix) with ESMTP id 1F00037B41E; Sat, 6 Apr 2002 14:40:48 -0800 (PST) Received: from hades.hell.gr (patr530-b187.otenet.gr [212.205.244.195]) by mailsrv.otenet.gr (8.12.2/8.12.2) with ESMTP id g36Mee2a029297; Sun, 7 Apr 2002 01:40:42 +0300 (EEST) Received: from hades.hell.gr (hades [127.0.0.1]) by hades.hell.gr (8.12.2/8.12.2) with ESMTP id g36MeeGM001564; Sun, 7 Apr 2002 01:40:41 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Received: (from charon@localhost) by hades.hell.gr (8.12.2/8.12.2/Submit) id g36MH9jF001309; Sun, 7 Apr 2002 01:17:09 +0300 (EEST) (envelope-from keramida@ceid.upatras.gr) Date: Sun, 7 Apr 2002 01:17:09 +0300 From: Giorgos Keramidas To: Murray Stokely Cc: freebsd-doc@freebsd.org Subject: Splitting the Handbook? (was: [a couple of new doc PRs]) Message-ID: <20020406221709.GA1181@hades.hell.gr> References: <20020404062954.6607E2E827@mail.freebsdmall.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="7JfCtLOvnd9MIVvH" Content-Disposition: inline In-Reply-To: <20020404062954.6607E2E827@mail.freebsdmall.com> User-Agent: Mutt/1.3.28i Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org --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