FreeBSD documentation format [was: Re: FAQ Updates]

[Lowell Gilbert]

linimon at lonesome.com  (Mark Linimon) writes:

> On Thu, Oct 06, 2005 at 07:22:55PM -0700, Gary W. Swearingen wrote:
> > > The problem is that the FAQ is trying to do to too many things.  I'm
> > > open to suggestions.
> > 
> > [but] some people will always want it to do all those things, and it's
> > hard to stop them.
> 
> I don't necessarily agree here.  I think a lot of commits get made to
> the thing because a) someone is tired of mentioning the same thing on
> the mailing lists over and over again and b) there's no other place in
> the project to put them.  If we figure out better places to put the
> information then I would like to believe the problems will sort themselves
> out in time.

See, to me that's exactly what a "FAQ" is for: collecting the answers
to questions that get asked frequently.  And making it convenient
enough to find answers in that people might try to do so before asking
the question.

> > but to make a practice of marking rotten entries "BROKEN" and removing
> > rotten entries which seem unlikely to ever be of any use to anyone.
> 
> No, not marked BROKEN, removed immediately.  Bad information is far
> worse than no information.  It is just that no one has set aside a long
> weekend (or something similiar) to chainsaw the thing.

In my experience, the bigger problem is entries that aren't wrong, but
are *slightly* outdated.  In a number of cases, the information can be
useful even so, but an applicability note helps until the entry is
updated.  [For example, a change in syntax between 4.x and 5.x.]

> > Amen.  The FAQ would be better as part of a wiki where more people
> > would hack on it.  But that won't happen without someone willing to
> > devote a lot of time to maintaining the server and some moderators.
> > And if there was such a wiki, it would probably grow like Topsy, with
> > work on Docbook docs dropping real far real fast. 
> 
> I don't think the latter is the case, either.  There are a lot of things
> where the The Right Thing for static content (that doesn't change from
> one minor release to another, say) is something like Docbook.
> 
> But for things like these 'knowledge-base' kinds of things that can
> change all the time, something more dynamic is probably better.

They *can* change all the time, but once created, most content tends
to stay useful for a long time.  I'm not sure whether that affects the
point at all, though.

> > But I've long wished that the Docbook docs be ditched after using
> > their content to seed a wiki.  A small subset of HTML is sufficient
> > markup for anybody but book publishers, IMO.

Visual markup, yes.  But markup serves other purposes, too, which you
don't get from a wiki.  Multiple output formats, for one thing.  I use
flat-text versions of the major documents more often than HTML, for
one thing.  And pdf quite often as well.  And I find the automatic
indexing and so forth to be fairly useful also.

Be well.