Re: A new strategy for internals documentation

> Date: Thu, 8 Aug 2013 14:07:51 -0700
> From: Doug Evans <[email protected]>
> Cc: Stan Shebs <[email protected]>, gdb <[email protected]>
> 
> On Thu, Aug 8, 2013 at 10:26 AM, Eli Zaretskii <[email protected]> wrote:
> >> Date: Wed, 07 Aug 2013 12:58:14 -0700
> >> From: Stan Shebs <[email protected]>
> >> CC: [email protected]
> >>
> >> > So how just declaring gdbint.texinfo dead and deleting it altogether?
> >>
> >> Isn't that going to be the end state of what I'm proposing? :-) I just
> >> added a path to conserve any bits that seem useful.
> >
> > My way is faster and easier.
> 
> Possibly alright, but what final result do we want?

The same as now: the internals manual is useless.

> > The grumbles come from people other than those who can provide the
> > documentation.  And the latter don't think we have a problem in the
> > first place.
> 
> If the latter includes me I disagree.

Disagree with what, and why?

> > Again, if we don't care about the documentation, then of course we
> > shouldn't care about poor information.  If we do care, then wiki is a
> > way to waste resources at best.
> 
> I disagree (that the wiki is a way to waste resources at best).

It is a waste because nothing good will ever come out of it.  It will
be a heap of notes various people at various times thought it would be
a good idea to share.  You cannot create a coherent document that way.

> > Why do you need development for comments?
> 
> He's referring to development of the comment->doc generator.

Why do we need that developed, if it already does the job?

> > The net result will be that the documentation will be unreadable.  Not
> > everybody who writes good code can write good documentation.
> 
> OTOH, It's easier to improve documentation over time.

Who will do that, and why?  Again, the core developers think that what
we have in the comments is enough, and if it is not enough, the
comments should be improved/expanded.  Why would someone invest
efforts in another resource?