Date: 07 Oct 2005 08:18:44 -0400 From: Lowell Gilbert <lgusenet@be-well.ilk.org> To: freebsd-doc@freebsd.org Subject: Re: FreeBSD documentation format [was: Re: FAQ Updates] Message-ID: <44fyrdfrkr.fsf@be-well.ilk.org> In-Reply-To: <20051007032725.GA8068@soaustin.net> References: <cq7jcquku8.jcq@mail.opusnet.com> <20051006135047.B0AB91551@fury.csh.rit.edu> <20051006170801.GB20088@soaustin.net> <20051006074516.3F3251551@fury.csh.rit.edu> <20051006080941.GD2627@soaustin.net> <20051006203845.GA28371@soaustin.net> <443bnezgbl.fsf@be-well.ilk.org> <20051007032725.GA8068@soaustin.net>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?44fyrdfrkr.fsf>