Re: A new strategy for internals documentation

[Eli Zaretskii <eliz@gnu.org>]

> cc: Yao Qi <yao@codesourcery.com>, stanshebs@earthlink.net, gdb@sourceware.org
> Comments: In-reply-to Eli Zaretskii <eliz@gnu.org>
>    message dated "Thu, 08 Aug 2013 20:30:24 +0300."
> Date: Thu, 08 Aug 2013 18:29:58 -0700
> From: John Gilmore <gnu@toad.com>
> 
> The real issue is not about where the information is stored.  The real
> issue is that people are evolving the code base without evolving the
> matching documentation.

Maybe it was so back when you started with this manual.  It is no
longer the case.  The real issue with this manual now is that it is
profoundly incomplete, so much so that some of the most important
parts of the GDB internals are not described at all, or their
description is just a listing of APIs without any glue.

By contrast, what _is_ there is being updated as GDB is developed, as
part of the development, and changes in GDB that invalidate what's in
the manual are accompanied by suitable changes to the manual.

>   *  Changes to Gdbint should not go through approval
> 
> If the team agrees with this, it's easy enough for any GDB maintainer
> to merely approve gdbint changes that are submitted as patches.

The approval part is a non-issue: I usually review patches to
documentation within hours of the RFA.  Note that people who mentioned
this issue didn't talk about approval, they talked about the writing
process itself.

> If [the internals manual] isn't doing that job, don't just change
> its format; change the process of updating the information, so that
> the information becomes relevant again.

People want _zero_ process on its behalf.  I tried to convince them
otherwise, offering help in many ways, including those you mentioned,
but you cannot convince someone to invest any effort when they want to
invest none.  So I gave up.  After all, a project in general, and its
documentation in particular, cannot be better than what the project's
community wants it to be.

Once again, the main problem (and some will say it's not a problem at
all) is that the majority of GDB developers don't see any need in this
manual's existence, or in any documentation of the internals besides
what's in the comments.  None whatsoever.  Until this changes, there's
no hope in improving the internals' documentation, and no need to
invest any additional effort in any replacements.