Date: Tue, 13 Oct 1998 15:15:48 +0200 From: Eivind Eklund <eivind@yes.no> To: "Robert A. Bruce" <rab@cdrom.com> Cc: doc@FreeBSD.ORG, rab@pike.cdrom.com Subject: Re: Publishing the FreeBSD Handbook and FAQ Message-ID: <19981013151548.43593@follo.net> In-Reply-To: <199810131212.FAA13369@pike.cdrom.com>; from Robert A. Bruce on Tue, Oct 13, 1998 at 05:12:35AM -0700 References: <19981013133644.50562@follo.net> <199810131212.FAA13369@pike.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Oct 13, 1998 at 05:12:35AM -0700, Robert A. Bruce wrote: > Eivind Eklund <eivind@yes.no> 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. It depends on whether we want it to feel as a coherent work or as a set of random collected writings. It is not very important, but it would add a much more professional feel to it. > >(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? It is a much richer markup, made for creating computer books. This mean there is support for tables, sidebars, formatting examples and code sanely, etc. It would allow you to make a truly good looking book instead of something that just look like a computer printout. O'Reilly has "standardized" on DocBook for their books (they request that all new books are marked up in this, though I've understood it as if they still sometimes accept things marked up in *roff). > >(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? No and yes, respectively. Nik has details on how to insert illustrations in his head (and I have them stored away on my hard drive, and can probably dig them up if need be). IMO: The handbook really need somebody to read it before publishing it :-) Eivind. 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?19981013151548.43593>