Merging the FAQ -> handbook, build time options, proof ofconcept patch

[Chuck Swiger]

Hi--

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 [1]; 
Sun's documentation is somewhat less creative in style, but is much more 
comprehensive in the detailed coverage of specific areas [2], and it also has 
a wider scope of organization. [3]

------
[1]: In particular, the Handbook is a noticably better read than the Solaris 
"System Administration Guide".

[2]: Sun has the resources to produce 600+ pages just on the DiskSuite RAID 
software, or their Solstice Backup stuff, etc etc.

[3]: 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" 
produces nothing.

Another example would be searching for "why does ruby dump core when I run 
portupgrade?"...

[ ... ]
> 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.

-- 
-Chuck