Doc BoF at EuroBSDCon

[Mark Linimon]

On Sun, 28 Nov 2004, Marc Fonvieille wrote:

> I see one important thing missing in this list, an important thing for
> the reader: the merge of the FAQ in the Handbook.  I'd put that on top
> of the list, very important informations are in the FAQ and people often
> miss them cause they are in another document, etc.

After tangling with the FAQ on several occasions, here's what I would
like to see happen:

 - the FAQ should remain -- but with a tiny subset of the text that's
   in there, e.g. things at the level of "what is FreeBSD".  These
   should be questions that answer "what" and "where".
 - questions that answer "how" should be either a) removed, or b) turned
   into a crossref into some other file, and the text migrated there.
   (example: the ppp chapter).  Whather that's the Handbook, or e.g.
   a separate ppp-howto, I don't have an opinion.  (Perhaps there are
   cases where one or the other is appropriate).
 - anything that's of the form "does XYZ card work" should be a crossref
   into the release notes.
 - anything that's of the form "what does terminology X mean" should be
   a crossref into the Glossary.  If the Glossary isn't its own page,
   it should be.
 - the bibliography should become its own page.

The "best of all possible worlds"?  That would be to take the things
of the form "I'm having trouble with my XYZ card" and turn them into
some kind of knowledge-base thing that would be much more lightweight
(e.g. not require DocBook) -- not so much because I or anyone else
here is allergice to DocBook, but to lower the 'barrier of entry' so
that people who are not on the doc project could contribute to it.

This would leave the handbook as a "start here and then do this" and
this new, theoretical, resource as the "I'm having a problem" resource.

Regardless of this long-term pipe dream, IMHO the above suggestions
ought to be considered in the short-to-medium term.

Yes, I'll summarize any consensus that arises about the FAQ and put
it up on the wiki.

mcl