Date: Thu, 6 Oct 2005 22:27:25 -0500 From: linimon@lonesome.com (Mark Linimon) To: "Gary W. Swearingen" <garys@opusnet.com> Cc: freebsd-doc@freebsd.org Subject: FreeBSD documentation format [was: Re: FAQ Updates] Message-ID: <20051007032725.GA8068@soaustin.net> In-Reply-To: <cq7jcquku8.jcq@mail.opusnet.com> References: <20051006135047.B0AB91551@fury.csh.rit.edu> <20051006074516.3F3251551@fury.csh.rit.edu> <20051006080941.GD2627@soaustin.net> <20051006170801.GB20088@soaustin.net> <443bnezgbl.fsf@be-well.ilk.org> <20051006203845.GA28371@soaustin.net> <cq7jcquku8.jcq@mail.opusnet.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20051007032725.GA8068>