From owner-freebsd-doc@FreeBSD.ORG Fri Oct 7 12:18:47 2005 Return-Path: X-Original-To: freebsd-doc@freebsd.org Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1C2E616A41F for ; Fri, 7 Oct 2005 12:18:47 +0000 (GMT) (envelope-from lgusenet@be-well.ilk.org) Received: from mail21.sea5.speakeasy.net (mail21.sea5.speakeasy.net [69.17.117.23]) by mx1.FreeBSD.org (Postfix) with ESMTP id B23E543D46 for ; Fri, 7 Oct 2005 12:18:46 +0000 (GMT) (envelope-from lgusenet@be-well.ilk.org) Received: (qmail 17928 invoked from network); 7 Oct 2005 12:18:45 -0000 Received: from dsl092-078-145.bos1.dsl.speakeasy.net (HELO be-well.ilk.org) ([66.92.78.145]) (envelope-sender ) by mail21.sea5.speakeasy.net (qmail-ldap-1.03) with SMTP for ; 7 Oct 2005 12:18:45 -0000 Received: by be-well.ilk.org (Postfix, from userid 1147) id DF0502E; Fri, 7 Oct 2005 08:18:44 -0400 (EDT) Sender: lowell@be-well.ilk.org To: linimon@lonesome.com (Mark Linimon) To: freebsd-doc@freebsd.org References: <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> From: Lowell Gilbert Date: 07 Oct 2005 08:18:44 -0400 In-Reply-To: <20051007032725.GA8068@soaustin.net> Message-ID: <44fyrdfrkr.fsf@be-well.ilk.org> Lines: 61 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.3 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: Subject: Re: FreeBSD documentation format [was: Re: FAQ Updates] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 07 Oct 2005 12:18:47 -0000 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.