Merging the FAQ -> handbook, build time options, proof ofconcept patch
cswiger at mac.com
Sat Dec 4 17:19:26 UTC 2004
I've been following this discussion with some interest and less angst, since
my FreeBSD doc needs are generally satisfied. The Handbook compares well with
high-quality docs such as Sun's AnswerBooks stuff.
To be more precise in that comparison, the Handbook contains some very good
writing and a relatively well-organized division of topics and chapters ;
Sun's documentation is somewhat less creative in style, but is much more
comprehensive in the detailed coverage of specific areas , and it also has
a wider scope of organization. 
: In particular, the Handbook is a noticably better read than the Solaris
"System Administration Guide".
: Sun has the resources to produce 600+ pages just on the DiskSuite RAID
software, or their Solstice Backup stuff, etc etc.
: See http://docs.sun.com. Note that it is gracefully multilingual, and
the discussion in the help topics is worth a read (although buried too many
clicks in). http://www.freebsd.org/docs.html or maybe
http://www.freebsd.org/doc/en_US.ISO8859-1/books/ is the closest thing FreeBSD
has to a "stable doc URL".
Tom Rhodes wrote:
> On Fri, 3 Dec 2004 13:02:12 -0600 (CST)
> Mark Linimon <linimon at lonesome.com> wrote:
[ ... ]
>>I agree that we don't want any overlap in the FAQ and the handbook,
>>or frankly for anyplace else for that matter. The overlap causes
>>confusion for both users and doc committers. That's one of the
>>reasons that the FAQ has rotted so badly.
> So, lemmie get this straight.
> Quick and question and answers in the faq, more thorough explinations
> moved into the handbook?
If you can't answer a frequent question with a paragraph or so, I would be
happy if the FAQ gave a brief intro and a link to a more comprehensive
description elsewhere. Whether elsewhere is in the handbook, some other
article, or elsewhere on the web shouldn't matter.
>>I see the FAQ serving as a "Start Here" document for people who
>>are not familiar with FreeBSD; as a place for "what is it/why should
>>I care/why did you do XYZ" thing. I see the handbook as "now that
>>I have FreeBSD installed, how do I do XYZ". The timeslice I had to
>>do the hackup job was insufficient to have gotten that across.
> Yes, I can see your point, valid it is.
Heh. My take on this is that whenever someone answers a question on a mailing
list with "This is a FAQ", such material actually ought to be in the FAQ.
In particular, searching the FAQ either via the find mechanism in one's
browser or via http://www.freebsd.org/search/search.html about an error like
"ad0: WARNING - WRITE_DMA interrupt was seen but timeout fired LBA=2928095"
Another example would be searching for "why does ruby dump core when I run
[ ... ]
> We need to close this matter and get back to work doing useful
> and good things. So, we have one problem and we need to choose
> what to do:
> Move most of the FAQ and keep the FAQ simple,
> Move all of the FAQ and either have it all in the handbook or as 1 file,
> Kill the FAQ off and start it a new.
#1 seems to be the closest to my thoughts. I can't say I find the current FAQ
to be very useful since it hides stuff too many clicks in and it doesn't
reward searching especially well. I would be happier with a plain-text FAQ in
Q&A format, or as a Docbook article rather than a book with subchapters.
The sendmail FAQ and the INN FAQ struck me as good FAQs, in that they can be
used successfully even to someone using less or i-search in Emacs on the ASCII
version. Newer versions use a split HTML layout, but at least put all of the
questions in one place that can be searched for easily.
More information about the freebsd-doc