FreeBSD documentation format [was: Re: FAQ Updates]

[Mark Linimon]

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.

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

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

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

I hope to God that we never do this.  I may be a minority of one, but
I find wiki markup language to be the worst abomination foisted off on
computer users since Windows NT 1.0.  I can _not_ work on editing wiki
data for more than about 10 minutes before I simply cannot stand it any
more and walk away.  It works almost totally and exactly the opposite
way that I would expect it to work at every turn (in particular, the
meta-escape sequences).

Having said that, I never really had a problem with Docbook and don't
understand why people find it so difficult.  In most of our documentation
we use a fairly small subset of the available tags and I find that generally
I can just use something that already exists as a template and I'm good to
go.  But I realize that a lot of people do have problems with it.  That,
and the fact that one needs to have a commit bit to make changes, makes it
less than an ideal medium for the more dynamic content.  But both of those
reasons make it much _closer_ to ideal for the more static content.  IMHO.

mcl