From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14828 invoked by alias); 26 Jun 2007 23:26:15 -0000 Received: (qmail 14818 invoked by uid 22791); 26 Jun 2007 23:26:14 -0000 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.31) with ESMTP; Tue, 26 Jun 2007 23:26:11 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 8244E2A96F0; Tue, 26 Jun 2007 19:25:41 -0400 (EDT) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id R8gSXRKEmENa; Tue, 26 Jun 2007 19:25:41 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id 5DA2F2A96EE; Tue, 26 Jun 2007 19:25:41 -0400 (EDT) Message-ID: <4681A073.5040209@adacore.com> Date: Tue, 26 Jun 2007 23:26:00 -0000 From: Robert Dewar User-Agent: Thunderbird 1.5.0.12 (Windows/20070509) MIME-Version: 1.0 To: Jim Blandy CC: Markus Deuling , Eli Zaretskii , pkoning@equallogic.com, eager@eagercon.com, stanshebs@earthlink.net, gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <467D5FEF.7010900@eagercon.com> <467D6D1F.7090507@earthlink.net> <467D6FB8.4080909@eagercon.com> <468009EA.4040504@eagercon.com> <18048.5444.903092.843811@pkoning.equallogic.com> <20070625193135.GA6391@caradoc.them.org> <4680199F.7020906@adacore.com> <46815BC2.9070204@de.ibm.com> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2007-06/txt/msg00322.txt.bz2 Jim Blandy wrote: > I want to hear an internals documentation advocate say, "I'm going to > work on the internals documentation because I think the date at which > user-visible project X is complete will move closer when I do so." > > I am *not* a seat-of-the-pants coder. Read prologue-value.h or > macrotab.h if you want to know my values. But I know that life is > short and uncertain, and that the pursuit of beauty has no regard for > that. Documentation is not about beauty, though some attention to readability and nice presentation is certainly worth while. If you follow a policy of implement now -- document never, you eventually get a mess in which you find it unreasonably hard to do anything. I find it a bit amazing for *anyone* to argue in favor of inadequate documentation!