From: Joel Brobecker <brobecker@adacore.com>
To: Robert Dewar <dewar@adacore.com>
Cc: Jim Blandy <jimb@codesourcery.com>,
Markus Deuling <deuling@de.ibm.com>,
Eli Zaretskii <eliz@gnu.org>,
pkoning@equallogic.com, eager@eagercon.com,
stanshebs@earthlink.net, gdb@sources.redhat.com
Subject: Re: What's an annex? stratum?
Date: Tue, 26 Jun 2007 23:39:00 -0000 [thread overview]
Message-ID: <20070626234056.GZ3706@adacore.com> (raw)
In-Reply-To: <4681A073.5040209@adacore.com>
> Documentation is not about beauty, though some attention to readability
> and nice presentation is certainly worth while. If you follow a policy
> of implement now -- document never, you eventually get a mess in which
> you find it unreasonably hard to do anything. I find it a bit amazing
> for *anyone* to argue in favor of inadequate documentation!
I think you misunderstood what Jim was saying. Jim documents his code
very well, and gives examples of that. What he says is that it's a lot
easier to maintain doco besides the associated code itself rather than
maintain a separate document (which is pretty much what you argued for).
Given the amount of resources that we have, this is probably the most
pragmatic approach to keeping our code documented.
--
Joel
next prev parent reply other threads:[~2007-06-26 23:39 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-06-23 18:01 Michael Eager
2007-06-23 18:57 ` Stan Shebs
2007-06-23 19:08 ` Michael Eager
2007-06-23 19:47 ` Eli Zaretskii
2007-06-23 20:51 ` Michael Eager
2007-06-23 21:23 ` Daniel Jacobowitz
2007-06-23 21:40 ` Michael Eager
2007-06-24 2:58 ` Eli Zaretskii
2007-06-24 4:32 ` Michael Eager
2007-06-25 18:03 ` Jim Blandy
2007-06-25 18:39 ` Michael Eager
2007-06-25 19:10 ` Jim Blandy
2007-06-25 19:26 ` Paul Koning
2007-06-25 19:32 ` Daniel Jacobowitz
2007-06-25 19:38 ` Robert Dewar
2007-06-25 19:48 ` Paul Koning
2007-06-25 20:09 ` Michael Eager
2007-06-25 20:40 ` Robert Dewar
2007-06-25 20:47 ` Robert Dewar
2007-06-25 20:31 ` Eli Zaretskii
2007-06-25 20:44 ` Robert Dewar
2007-06-25 21:00 ` Eli Zaretskii
2007-06-25 21:03 ` Robert Dewar
2007-06-25 21:06 ` Robert Dewar
2007-06-26 18:34 ` Markus Deuling
2007-06-26 18:36 ` Robert Dewar
2007-06-26 21:55 ` Jim Blandy
2007-06-26 22:14 ` Nick Roberts
2007-06-26 23:26 ` Robert Dewar
2007-06-26 23:39 ` Joel Brobecker [this message]
2007-06-26 23:43 ` Robert Dewar
2007-06-27 0:32 ` Jim Blandy
2007-06-27 0:42 ` Robert Dewar
2007-06-27 3:22 ` Eli Zaretskii
2007-06-27 0:23 ` Michael Eager
2007-06-25 20:42 ` Eli Zaretskii
2007-06-25 20:23 ` Eli Zaretskii
2007-06-25 21:52 ` Jim Blandy
2007-06-26 1:04 ` Paul Koning
2007-06-25 20:37 ` Eli Zaretskii
2007-06-25 20:15 ` Eli Zaretskii
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=20070626234056.GZ3706@adacore.com \
--to=brobecker@adacore.com \
--cc=deuling@de.ibm.com \
--cc=dewar@adacore.com \
--cc=eager@eagercon.com \
--cc=eliz@gnu.org \
--cc=gdb@sources.redhat.com \
--cc=jimb@codesourcery.com \
--cc=pkoning@equallogic.com \
--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