From owner-freebsd-doc Sun Apr 7 16:38:20 2002 Delivered-To: freebsd-doc@freebsd.org Received: from lists.blarg.net (lists.blarg.net [206.124.128.17]) by hub.freebsd.org (Postfix) with ESMTP id 09A6937B416; Sun, 7 Apr 2002 16:38:14 -0700 (PDT) Received: from thig.blarg.net (thig.blarg.net [206.124.128.18]) by lists.blarg.net (Postfix) with ESMTP id AA84FBD96; Sun, 7 Apr 2002 16:38:13 -0700 (PDT) Received: from localhost.localdomain ([206.124.139.115]) by thig.blarg.net (8.9.3/8.9.3) with ESMTP id QAA13091; Sun, 7 Apr 2002 16:38:12 -0700 Received: (from jojo@localhost) by localhost.localdomain (8.11.6/8.11.3) id g37NcCm82626; Sun, 7 Apr 2002 16:38:12 -0700 (PDT) (envelope-from swear@blarg.net) To: Giorgos Keramidas , Murray Stokely Cc: freebsd-doc@FreeBSD.ORG Subject: Re: Splitting the Handbook? (was: [a couple of new doc PRs]) References: <20020404062954.6607E2E827@mail.freebsdmall.com> <20020406221709.GA1181@hades.hell.gr> From: swear@blarg.net (Gary W. Swearingen) Date: 07 Apr 2002 16:38:12 -0700 In-Reply-To: <20020406221709.GA1181@hades.hell.gr> Message-ID: Lines: 160 User-Agent: Gnus/5.0808 (Gnus v5.8.8) XEmacs/21.1 (Cuyahoga Valley) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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 This discusses the organization of FreeBSD documentation, but is mostly limited to comments on the reorganization of Books. (I have more to add to the outline, but I'll save it for smaller messages.) This is off the top of my head (about two hours deep) and that shows in the form of incompleteness and loose writing, but I hope it's helpful anyway. If it's too long for you, just take a look at sections 1.2 and 2.3. "Publish", below, refers only to the paper form, not electronic forms. 1. FreeBSD documentation: 1.1. Division (better documented elsewhere): -- Manuals (AKA Manual Pages). -- FreeBSD.org WWW-only pages. -- Books, including the FAQ-on-all-subjects. -- Articles -- Mailing list archives -- External WWW and FTP sites, including Indexes, HOWTOs, e-mag articles, tips, etc. 1.2. Cross-referencing of documentation: This is an issue that should be resolved and documented (probably with the involvement of "core"). Obviously, all documents reference the manuals, but to what extent, if any, do manuals reference other docs and do other docs reference each other. And how do they reference each other. By freebsd.org URL? file:/usr/share/... URL? Chapter, Section, Sub-section Title? There are very important work-hour implications from decisions on this topic, mostly because of maintenance issues. This has a connection to the subject of documentation division also. Does it make sense to have articles which may not be referenced by the books, for example (and assuming that there is any such restriction)? 1.3 Standards and related issues: The FPD Primer has what exists. FDP should probably document how standards are established and changed, reasons for level of detail, etc. 2. Books: 2.1. Purpose of books. The FDP should document why it's organized much of the documentation in the form of books. The following are important considerations with the third being the determining factor. Most (or all) of the detail on these considerations is contained in other sections of this message. 2.1.1 The goals and desires of the publisher in the absence of the FDP. To sell books. The books should contain considerable duplication so that they are stand-alone for the purposes of satisfying the customer who buys one book. Some subjects are just too esoteric to be worth- while to publish. 2.1.2 The goals and desires of the FDP in the absence of the publisher. No reason for books, really. A bunch of sections or articles would do just fine. Duplication should be almost nil. The info should be targeted at nobody in particular except the person interested in the specifically-indentified subject matter. No subject is too esoteric as long as there is someone who wants to write about it. 2.1.3 The goals and desires of the FDP in the presence of the publisher. There are several reasons that the FDP should accommodate the publisher except in rare instances. -- The two groups help each other. (It would help some justify work on mostly-publisher-helpful work (mostly duplication for differently- targeted books), to know how much help flowed from the publisher.) -- Some FDP people will be using the published books. (I doubt if I will. I wonder what the ratio is.) -- All FDP people should want to see good FreeBSD books available. The troublesome issues probably are: -- How much duplication is the FDP willing to create and maintain? -- The referencing of non-published docs in published docs. (Is there a technological solution to this one? Is it already in place?) -- (This should be a troublesome issue, but apparently isn't:) Who owns the documentation and related matters and how is it documented? 2.2. Size of Books. For non-publishing purposes, it doesn't matter enough to worry about. Most access is by sub-sections or collections of those which have no practical size restrictions. For the same and more obvious reasons, the FDP should adapt to the needs of the publisher regarding the size of the books. I suppose this is somewhere around 400-500 pages for basics books and 500-600 for advanced books. 2.3. Book content divisions: basics/advanced server/workstation user/sys_admin subject-related books (eg, Mailing, Developing) The publisher would probably prefer the basics/advanced division with the overflow of the first going into the second and the overflow of the second being omitted or existing only in the electronic version. The server/workstation and user/sys_admin divisions would be reasonable ones for a purchaser of books and so maybe for a publisher too, but the amount of duplication that should be a part of such books renders this unacceptable for the FDP, since there are reasonable alternatives. And despite the duplication, most people would need both books anyway. :( The publisher might be benefited from an assumption that 99% purchasers will need or want to buy both books. The straightforward method would be to simply have Vols I&II, arranged simple order like most-often needed for reference and least-often needed (like installation stuff and advanced stuff), but I suspect that publishers don't think this way and would prefer a division in which they can at least pretend that some customers can get by with only one book. The ideal division from the buyer's POV would be by about three levels of expertise, but that involves too much duplication to be practical. I think the best practical scheme is to have three books: -- Stuff you might need to know before, during, and just after installation. (At the newbie level of OS refugees. With Unix intro.) -- Stuff you need to know from day to day, including standard and/or common applications. (At moderately advanced level.) -- Stuff you rarely need to know, including uncommon applications. (Same level as second book.) But "The Complete FreeBSD" by Greg Lehey serves the purpose of the first adequately enough so that the FDP should be satisfied with the kludge of merging newbie-level intro stuff with more advanced stuff that's simply standard or common, to accommodate both publishers. 2.4. Transistion plans. Big split or breaking out pieces? 2.5. Level of detail. This should be handled by having (sub)sections which have content which is too detailed or too advanced or too crude for publishing segregate that information out into a specially-marked subsection which is only part of the electronic version. This would sometimes require extra writing of introductions to the topic so the published version doesn't look incomplete, but usually the introduction would be needed anyway. 3. More topics which have been (and will be) discussed: -- searching; methods, tools -- indexing and tabling of content; -- relationship of articles to other documents; -- relationship of manuals to other documents; -- Special books like Developers Guide, ... To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message