Re: A new strategy for internals documentation

On Thu, Aug 8, 2013 at 2:55 PM, Eli Zaretskii <[email protected]> wrote:
>> Date: Thu, 8 Aug 2013 14:07:51 -0700
>> From: Doug Evans <[email protected]>
>> Cc: Stan Shebs <[email protected]>, gdb <[email protected]>
> [...]
>> > 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?

I disagree with the statement "the latter don't think we have a problem".
We do have a problem: I think our internals documentation needs improving.

>> > 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.

I think we'll have to agree to disagree that nothing good will come out of it.
For example, gdb's current wiki pages are useful, and are edited far
more often than gdbint.texinfo (AFAICT).

>> > 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?

Assuming it doesn't have latent bugs that no one has tripped over yet,
and assuming it does everything we want, now and tomorrow.

>> > 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?

I'm one that thinks that there is not enough, and that expanding the
comments is not enough.  For one there's a higher level / descriptive
view that's missing with that approach.  Plus the S/N ratio when faced
with reading all the source code is much lower than when able to
browse something generated from the comments in the code.