Nguyen Thai Ngoc Duy [off-list ref] writes:
Looks good. I don't really like ending a sentence with semicolon, but
that's just my taste.
I tend to do enumerated list like "A; B; and C." Perhaps just a personal
taste.
I wonder if we should also point to relevant source files, so if this
document becomes out of date, the readers can jump in the source and
verify themselves (perhaps coming up with patches to this doc)?
I suspect that is a sure way to guarantee the document to go stale.
I didn't like the way I explained the cache-tree entry order. Was it
understandable?
I am wondering if an illustration with an example might be in order. I
think anybody halfway intelligent may be able to get a fuzzy idea of what
is going on by looking at the output from test-dump-cache-tree after
"reset --hard && write-tree" and then by comparing it with the output from
test-dump-cache-tree after running ">t/something && git add t/something"
(which invalidates the top-level tree and t/ subtree). But a well written
documentation should be able to help clarifying the idea obtainable that
way. I don't think what I wrote in the previous message is sufficient
even for that (i.e. comparing the two output would give you better
explanation of what is going on than what I wrote--iow, what I wrote may
not be very useful for people who are motivated to learn).
On Wed, Mar 2, 2011 at 1:02 PM, Junio C Hamano [off-list ref] wrote:
quoted
I wonder if we should also point to relevant source files, so if this
document becomes out of date, the readers can jump in the source and
verify themselves (perhaps coming up with patches to this doc)?
I suspect that is a sure way to guarantee the document to go stale.
No it does not. The point is to make it easier for readers to help
themselves when they suspect the document is not entirely correct.
I didn't like the way I explained the cache-tree entry order. Was it
understandable?
It is, although I'm wondering if it's just like memcmp() order with
parent component cut out.
I am wondering if an illustration with an example might be in order. I
think anybody halfway intelligent may be able to get a fuzzy idea of what
is going on by looking at the output from test-dump-cache-tree after
"reset --hard && write-tree" and then by comparing it with the output from
test-dump-cache-tree after running ">t/something && git add t/something"
(which invalidates the top-level tree and t/ subtree).
A short example would be great. test-dump-cache-tree might not be.
Last time I read its output, I wasn't sure I understood. Maybe because
I ran it on git.git and did not compare two outputs.
But a well written
documentation should be able to help clarifying the idea obtainable that
way. I don't think what I wrote in the previous message is sufficient
even for that (i.e. comparing the two output would give you better
explanation of what is going on than what I wrote--iow, what I wrote may
not be very useful for people who are motivated to learn).
--
Duy
On Tue, 2011-03-01 at 22:02 -0800, Junio C Hamano wrote:
I didn't like the way I explained the cache-tree entry order. Was it
understandable?
I am wondering if an illustration with an example might be in order. I
think anybody halfway intelligent may be able to get a fuzzy idea of what
is going on by looking at the output from test-dump-cache-tree after
"reset --hard && write-tree" and then by comparing it with the output from
test-dump-cache-tree after running ">t/something && git add t/something"
(which invalidates the top-level tree and t/ subtree). But a well written
documentation should be able to help clarifying the idea obtainable that
way. I don't think what I wrote in the previous message is sufficient
even for that (i.e. comparing the two output would give you better
explanation of what is going on than what I wrote--iow, what I wrote may
not be very useful for people who are motivated to learn).
Perhaps I'll be able to put some time into reading the work you guys are
doing.... I can definitely put the "newbie goggles" on if I do.
--
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59