Re: What's an annex? stratum?

[Robert Dewar <dewar@adacore.com>]

Jim Blandy wrote:
> Robert Dewar <dewar@adacore.com> writes:
>> It is hard to read into this a viewpoint that says that time spent on
>> the internals documentation is OK if it is in the source files, but not
>> if it is in separate files.
> 
> You're right; this doesn't make sense as written.
> 
> I write the comments in the code before I write the code, because I've
> found that the effort of trying to explain what I'm about to try to do
> helps clarify my own understanding a great deal.  For me, at least, it
> makes enough of a difference that I'm sure I come out ahead, if you
> include debugging time.

I find the same thing, and even more these days, I find I can't rely
on my memory so well, so if I come back to code I wrote 6 months ago,
I need the documentation as much as anyone :-)
> 
> In other words, if the internals documentation is written before the
> code, then, for me, it is a worthwhile investment.  In that case, I do
> believe that writing that documentation brings the completion date
> closer, and I write it.  I don't know whether other contributors need
> this particular crutch; I'm pretty sure some don't.
> 
> The only other time I write explanations is when someone asks for
> help; here, again, the investment is worthwhile, because someone is
> about to go off and write some code, and I can bring their completion
> date closer.  Most of what I've contributed to gdbint.texinfo got in
> there because Eli liked something I'd written on the mailing list and
> asked me to put it there.

certainly fair enough.

One thing that I have found helpful is to ask newcomers to report
as bugs cases in which the code is not clear, and then when the
explanations are given, or the detective work completed, help
write the documentation they found missing.