Subject: Re: [PATCH v3 0/5] Fixes for Documentation/MyFirstObjectWalk.txt

From: Junio C Hamano <[email-masked]>
Date: Mon, 25 Mar 2024 10:50:05 -0700

Dirk Gouders <[email-masked]> writes:

> The 3rd iteration for this series.
>
> I tried to credit Kyle's suggestions for 4 and 5 with Helped-by tags and
> hope it was adequate to do so.  Actually, at least #4 was a lot more
> than a Helped-by, I would say...

It seemed adequate, at least to me, but I'll leave the final say up
to Kyle.

I left a few comments but overall the series is looking much nicer.
Thanks for working on it (and thanks for reviewing and helping,
Kyle).

This is an unrelated tangent, but I wonder if we can come up with a
way to find breakages coming from API updates to these "tutorial"
documents.  The original "user-manual" also shares the same issue,
and the issue may be deeper there as it also needs to catch up with
end-user facing UI updates.  In any case, we somehow ended up with
two more "tutorial"-ish documents (MyFirstContribution.txt is the
other one) that somebody needs to keep an eye on.

Ideally if we can have automated tests, it would be nice.  Perhaps
sprinkling some special instruction in comments that is hidden from
AsciiDoc mark-up to help our custom program to assemble the bits
into the state of the tutorial program that the readers should be
arriving at at different points in the tutorial document, and make
sure they compile, link, and test well?  Or "follow one of our three
tutorial documents to the letter to see if they need adjusting, and
come up with a set of patches to adjust them" can be listed as one
of the microproject ideas?  I'll leave a #leftoverbits mark here, but
what I want to see discussed (and eventually implemented) is not the
clean-up itself (which can go stale over time) but the strategy to
keep the "tutorial" material up-to-date.

THanks.