Re: What's an annex? stratum?

[Michael Eager <eager@eagercon.com>]

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