This is the mail archive of the mailing list for the GDB project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: What's an annex? stratum?

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

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

No one is pursuing beauty. This is the pursuit of utility.

-- Michael Eager 1960 Park Blvd., Palo Alto, CA 94306 650-325-8077

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]