From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10183 invoked by alias); 27 Jun 2007 00:23:00 -0000 Received: (qmail 10175 invoked by uid 22791); 27 Jun 2007 00:23:00 -0000 X-Spam-Check-By: sourceware.org Received: from shell4.bayarea.net (HELO shell4.bayarea.net) (209.128.82.1) by sourceware.org (qpsmtpd/0.31) with ESMTP; Wed, 27 Jun 2007 00:22:57 +0000 Received: (qmail 19113 invoked from network); 26 Jun 2007 17:22:55 -0700 Received: from 209-128-106-254.bayarea.net (HELO ?192.168.20.7?) (209.128.106.254) by shell4.bayarea.net with SMTP; 26 Jun 2007 17:22:55 -0700 Message-ID: <4681ADDE.6060106@eagercon.com> Date: Wed, 27 Jun 2007 00:23:00 -0000 From: Michael Eager User-Agent: Thunderbird 1.5.0.9 (X11/20070102) MIME-Version: 1.0 To: Jim Blandy CC: Markus Deuling , Eli Zaretskii , Robert Dewar , pkoning@equallogic.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=UTF-8; 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/msg00328.txt.bz2 Jim Blandy wrote: > Time spent on the internals documentation has, itself, no effect on > users' experience with GDB. It's only worthwhile if that time, plus > the time then spent doing something users *will* notice, is less than > the time needed just to do something user-visible without internals > documentation. Time spent on internal documentation facilitates others in doing the work you describe as worthwhile. If the complaint is that there are not many people working on GDB, part of the problem, speaking from experience, is that GDB is fairly opaque. Flow of control is convoluted. The organization of the code tries to be modular, but that seems often more in the style than the substance. The alternate "ask a question, we'll be happy to help" tends to work better in theory than in practice. The answers seldom provide much of an overview of operation in an area, nor do they provide the detail which is commonly included in the documentation. Frequently, the answers veer off on tangents (such as this discussion, which started with a question about what's a stratum, still unanswered) or into commentary (such as "the new scheme is much better"). > 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." The people who would most profit from improved documentation are the people who are trying to understand the code. The people who are best able to improve the documentation are the ones who have experience with it. If you look at improvement in GDB as a single-person effort, then for the experienced person, it's always better to do it yourself rather than take the time to facilitate someone less experienced. If you look at it as a multi-person effort, where an expenditure of effort on documentation will result in greater improvements done by more people, then there's greater value. > 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. No one is pursuing beauty. This is the pursuit of utility. -- Michael Eager eager@eagercon.com 1960 Park Blvd., Palo Alto, CA 94306 650-325-8077