linimon@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.
_______________________________________________
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org"