From: Eli Zaretskii <eliz@gnu.org>
To: Doug Evans <dje@google.com>
Cc: stanshebs@earthlink.net, gdb@sourceware.org
Subject: Re: A new strategy for internals documentation
Date: Thu, 08 Aug 2013 21:56:00 -0000 [thread overview]
Message-ID: <8361vfu9t4.fsf@gnu.org> (raw)
In-Reply-To: <CADPb22ToXn8aypnpyHEFrUw_yQQiib=ieCj7WbQLSaZQM00RVg@mail.gmail.com>
> Date: Thu, 8 Aug 2013 14:07:51 -0700
> From: Doug Evans <dje@google.com>
> Cc: Stan Shebs <stanshebs@earthlink.net>, gdb <gdb@sourceware.org>
>
> 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?
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?
next prev parent reply other threads:[~2013-08-08 21:56 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-08-06 22:26 Stan Shebs
2013-08-07 4:28 ` Eli Zaretskii
2013-08-07 19:58 ` Stan Shebs
2013-08-08 17:28 ` Eli Zaretskii
2013-08-08 21:08 ` Doug Evans
2013-08-08 21:56 ` Eli Zaretskii [this message]
2013-08-08 23:03 ` Stan Shebs
2013-08-09 8:08 ` John Gilmore
2013-08-09 9:53 ` Eli Zaretskii
2013-08-09 9:35 ` Eli Zaretskii
2013-08-09 23:04 ` Stan Shebs
2013-08-09 9:53 ` Mark Kettenis
2013-08-09 23:28 ` Stan Shebs
2013-08-08 23:04 ` Doug Evans
2013-08-09 9:13 ` Eli Zaretskii
2013-08-10 1:13 ` Yao Qi
2013-08-21 18:09 ` Steinar Bang
2013-08-21 20:02 ` Eli Zaretskii
2013-08-22 18:29 ` Steinar Bang
2013-08-08 3:45 ` Yao Qi
2013-08-08 17:31 ` Eli Zaretskii
2013-08-09 1:30 ` John Gilmore
2013-08-09 9:26 ` Eli Zaretskii
2013-08-09 18:16 ` Tom Tromey
2013-08-09 18:36 ` Eli Zaretskii
2013-08-09 22:31 ` Stan Shebs
2013-08-09 23:32 ` Matt Rice
2013-08-10 2:24 ` John Gilmore
2013-08-08 20:43 ` Tom Tromey
2013-08-08 20:57 ` Doug Evans
2013-08-08 20:41 ` Tom Tromey
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8361vfu9t4.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=dje@google.com \
--cc=gdb@sourceware.org \
--cc=stanshebs@earthlink.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox