From owner-freebsd-doc Tue Oct 13 05:10:50 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id FAA15676 for freebsd-doc-outgoing; Tue, 13 Oct 1998 05:10:50 -0700 (PDT) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from pike.cdrom.com (pike.cdrom.com [204.216.28.222]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id FAA15671 for ; Tue, 13 Oct 1998 05:10:49 -0700 (PDT) (envelope-from rab@pike.cdrom.com) Received: from pike.cdrom.com (localhost.cdrom.com [127.0.0.1]) by pike.cdrom.com (8.8.8/8.8.7) with ESMTP id FAA13369; Tue, 13 Oct 1998 05:12:35 -0700 (PDT) (envelope-from rab@pike.cdrom.com) Message-Id: <199810131212.FAA13369@pike.cdrom.com> To: Eivind Eklund cc: "Robert A. Bruce" , doc@FreeBSD.ORG, rab@pike.cdrom.com Subject: Re: Publishing the FreeBSD Handbook and FAQ In-reply-to: Your message of "Tue, 13 Oct 1998 13:36:44 +0200." <19981013133644.50562@follo.net> Date: Tue, 13 Oct 1998 05:12:35 -0700 From: "Robert A. Bruce" Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Eivind Eklund said... >If you have some amount of manpower, it would be prudent to go through >the entire handbook and 'take notes' of what needs to be changed. > >Ideally, the entire handbook should have a careful editor go through >and fix it to >(1) Have the same style throughout (language choices) Different parts to the book have different styles, some parts are "folksy" while others are more formal. But I don't agree that this is necessarily a "problem" that needs to be fixed. As long as the information is technically correct, I don't think it is a big deal if the style varies from chapter to chapter. >(2) Have each section organized in a 'build-up' fashion, starting from > almost no assumptions about what the user knows (or references to > what should have been read before) and building up to the full > gory details. >(3) Be fully marked up in DocBook instead of LinuxDoc. What is the advantage of DocBook over LinuxDoc? >(4) Contain relevant illustrations. Do you have a list of where illustrations are needed? Is there a standard way of putting illustrations into an SGML document? -bob To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message