Date: Tue, 19 Feb 2002 23:11:18 -0500 From: Tom Rhodes <darklogik@pittgoth.com> To: "Gary W. Swearingen" <swear@blarg.net> Cc: Michael Lucas <mwlucas@blackhelicopters.org>, Jay Edwards <jayed@jayed.com>, bmah@FreeBSD.ORG, freebsd-doc@FreeBSD.ORG Subject: Re: BSDCon Doc BoF Notes Message-ID: <3C7321E6.4030001@pittgoth.com> References: <200202182315.g1INFpc93221@bmah.dyndns.org> <3C719161.5090803@pittgoth.com> <20020219050357.GN42451@jayed.com> <20020218191647.A11924@blackhelicopters.org> <fg1yfgdh8b.yfg@localhost.localdomain>
next in thread | previous in thread | raw e-mail | index | archive | help
Gary W. Swearingen wrote: >Michael Lucas <mwlucas@blackhelicopters.org> writes: > >>Of course, other suggestions are welcome. This bikeshed is going to >>be around a while, I'm afraid. >> > >Paper book readers don't care whether book is split into small >HOWTO-sized pieces because they'll need to buy big books in any case. > I can agree with this. I know that a larger book catches my eye first due to size, one would expect a great deal of content. > >Their only concern is how expensive each book is and how many they will >need to buy. Trying to divide the current handbook by subject seems to >me a useless cause for paper books. Almost everyone would need all the > Real quick, I can again agree. Cost is a big issue with many people, I do look at price of hardware, books, ISP's. Many people I talk to and work with are the same way. > >books. The only reasonable division is by detail and that would take >much rewriting and duplication of material. Ideally, each topic could >have two or three levels of presentation, which could be separated for >three (or more for the most detailed (man page?) level) paper books (and >made accessible via link for paged digital versions). It sounds like >too much work, but except for a simple splitting of the manual into >all-needed-by-all parts (maybe with the minor help of segregating >networking or other big categories), it seems like the only reasonable >scheme. For instance in the "Security" section, the "Kerberos" topic >could have a short intro just to let people know why they might want to >investigate it further and then referrence the topic as in the "Details" >book. Topics would have widely varying coverage in the "Basics" book, >as commonly needed by users, but probably influenced by the need to keep >the Basics book under some size limit. > This may be more work than called for, but, if a patch is generated for the handbook on your system, and I have the same revision as you have, then the patch should work on my copy also. We could seperate the handbook, make one area for online browsing, and one for the full version. The only problem with this, is that when a patch is applied, someone may need to apply them to both versions. Or, depending on how the layout, the patch may need completely regenerated for one or the other. Maybe more work, but ask yourself, would it be worth it. This may raise barriors for people who WANT to be committers some day... But its something that experiance would teach. > > >The organization of the paged digital version (eg, HTML) hardly matters >as long as appropriate tables of content and indexes are provided. I'd >prefer these not even exist for only the Handbook, but also cover the >Articles, FAQ, and all other FDP docs. > >I hope there will always be a fully-combined ASCII version of the >handbook since that's the only one that's easily navigated/searched. >I found this to be one of the great advantages over Linux HOWTOs. >(Don't ask why I didn't make myself one.) > >Finally, several people have mentioned that multiple small books would >be easier for people (mostly doc people) to deal with. I have little >experience here, but it seems to me that Chapters and Articles are the >natural chunks that people deal with at any one time, and the number of >those grouped into any one book should barely matter. > > Large chapters, are hard to navigate through. If you notice a spelling, grammer, or other type of error, i'll be the first to admit, its difficult to find sometimes. Once in awhile i'll read the pr 2 or 3 times just to be sure i've found the right area, or even to help find the area. If some of the chapters were maybe broken down a bit, then yes, it may be easier for both indexing and editing purposes. Bringing up another point, you could always even argue that "The Complete FreeBSD" is more like an almost all-in-one guide to setting up this, setting up that, as many 'advanced' topics are covered, like DNS. Anyway, i'm done for now, and will wait for comments -- Tom Rhodes 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?3C7321E6.4030001>