Date: 07 Apr 2002 16:38:12 -0700 From: swear@blarg.net (Gary W. Swearingen) To: Giorgos Keramidas <keramida@FreeBSD.ORG>, Murray Stokely <murray@FreeBSD.ORG> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: Splitting the Handbook? (was: [a couple of new doc PRs]) Message-ID: <mnhemn13mj.emn@localhost.localdomain> In-Reply-To: <20020406221709.GA1181@hades.hell.gr> References: <20020404062954.6607E2E827@mail.freebsdmall.com> <20020406221709.GA1181@hades.hell.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?mnhemn13mj.emn>