Re: Git Contributor' summit: Documentation,

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 23, 2026, 15:15 UTC
Message-ID: <xmqqbj9oc83t.fsf@gitster.g>
In-Reply-To: <871pak1151.fsf@emacs.iotcl.com>

Toon Claes <toon@iotcl.com> writes:

> I've expressed myself multiple times as well how excited I am to have
> Julia working on this, but it cannot be expressed enough.

;-)

Show 7 quoted lines

>> list, ever. I just hope that old-timers who really do not need the
>> documentation nor understand the need of those who do need it show
>> enough appreciation for the fresh views and for Julia's understanding
>> of the target audience.)
>
> I think the old-timers do, but it takes skills to have a very deep
> understanding and still being able to explain things to newbies.

Not just these two skills, but you need to know what are the points new people find hard to get when they are starting, and that is the weakest spot for our old-timers.

Show 7 quoted lines

>> There was support for replacing outdated material and for merging useful
>> improvements, then iterating, rather than trying to perfect everything
>> before it lands. Bringing user feedback to the list without flooding it
>> remains a challenge.
>
> Iteration will be key here, and I would say some steps have been taken
> already. Very tiny steps though.

IIRC, the view in the room was in favor of keeping and incrementally improving the manual pages and reference material while rewriting tutorials and material on concepts from scratch. I very much agree with the "rewrite from scratch" part, because the concepts have evolved and the world view have been updated even if the concepts at the very core of the system may have not changed.