Re: A new strategy for internals documentation

[Doug Evans <dje@google.com>]

On Thu, Aug 8, 2013 at 10:26 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 07 Aug 2013 12:58:14 -0700
>> From: Stan Shebs <stanshebs@earthlink.net>
>> CC: gdb@sourceware.org
>>
>> > 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?
[What are we working towards?]

>> People do want internals documentation, we hear grumbles about it on a
>> weekly basis.
>
> 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.
[I think the latter includes me, IIUC, but I could be wrong.]

>> >> *** Migration of gdbint.texinfo to wiki
>> >
>> > Wiki is a bad idea, because there's virtually no control on the
>> > quality of the information there.
>>
>> That's true now, but I don't think I've heard of anybody being misled by
>> poor information on the GDB wiki.
>
> 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).

>> > AFAIK, Doxygen cannot generate an Info manual, only HTML.  If so, this
>> > would be a serious downside that you don't mention.
>>
>> Hmm, I'm perhaps prejudiced since I haven't looked at any info file in
>> probably a decade.  Are many people using them still?
>
> I do, quite a lot.  Besides, Info is the official format of GNU
> documentation, you will have hard time convincing the FSF to demote an
> existing manual.
>
>> > If we want to keep the documentation in the sources, why not use the
>> > same system as libiberty?
>>
>> It's plausible, but idiosyncratic.  How much development does it get,
>> vs Doxygen?
>
> Why do you need development for comments?

He's referring to development of the comment->doc generator.
[right?]

>> > Not having a review process for documentation is an "upside"
>> > because?...
>>
>> I think it's time-consuming overkill for tutorials and howtos.  An
>> underlying implicit goal here is to encourage contribution, not think of
>> ways to chase people away.
>
> 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.
[it's more important to get code right sooner than later]