Re: Git Contributor' summit: Documentation, was: Re: My summary of the Git Contributors' Summit 2026, was Re: Git v3.0 timeline, was Re: What's cooking in git.git (Sep 2026, #08)

[Toon Claes <toon@iotcl.com>]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Documentation
>
> Julia's work highlights the gap between documentation written by people
> who know Git inside out and users who do not yet know what objects, the
> index, or upstream mean. We need approachable learning material as well as
> reference documentation. Both need work; keeping manpages concise does not
> mean they cannot have better explanations and examples. (Personal note: I
> am beyond excited that Julia, whose work I have always admired, 

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

> got interested in improving Git's documentation, which is in dear need
> of being improved, mainly because it does not cater to the majority of
> Git users out there who are unlikely to wander onto the Git mailing
> 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.

> Discoverability matters, too. The website (https://git-scm.com/) needs
> clearer entry points for learning Git, and existing guides are harder to
> find than manpages. Missing subsection links are another improvement we
> could make incrementally. (Personal note: Judging by the history of that
> site, I do wonder whether the core Git contributors are interested in
> helping this effort at all. For example, there are a growing number of PRs
> suggesting to add new UIs to the growing list, but I gave up reviewing
> them because I was the only one doing so.)

I share the blame here. Some time ago I volunteered to step in to do
maintainance work on git-scm.com, but I haven't been devoting as much
time as I would like.

Talking about the UI list, that's a problem which I'm not sure worth
discussing here, but to folks interested, there is some context in the
PR[1] you created.

[1]: https://github.com/git/git-scm.com/pull/2179

> 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.

Finding a medium to gather user feedback is the problem. I think Discord
is a better place than the mailing list (assuming that's what you mean
by "list"?).

> The current funding covers only 100 hours split between two people.
> Additional project and company funding was encouraged; brian, Emily, and
> Mark offered to explore company support. (Personal note: I had tried, back
> when GitHub still funded my team, to start something like that, without
> any success. To the contrary, even Git for Windows and Git Credential
> Manager got defunded.)
>
> On the tooling side, using only Asciidoctor instead of maintaining both
> AsciiDoc and Asciidoctor support was proposed as a possible Git v3.0
> change. Distribution support and rendering differences need checking, with
> doc-diff suggested for comparing the outputs. Patrick filed an issue
> during the discussion. (Personal note: AFAIU the AsciiDoc spec is now
> maintained by Asciidoctor, and I am aware already of one change that was
> made to the spec without adapting AsciiDoc accordingly. So the entire
> discussion might be quite moot already.)
>
> Other ideas included richer diagrams for HTML while retaining text
> versions for manpages

This feels feasible. I think brian suggested to use Open Blocks[2] and
have a man-page ASCII version next to /something else/.

[2]: https://docs.asciidoctor.org/asciidoc/latest/blocks/open-blocks/

> and privacy-respecting traffic measurements to help prioritize
> documentation work.

For the record, we have been talking about this[3] in the past.

[3]: https://github.com/git/git-scm.com/issues/2054

> No diagram format was chosen

Yeah, that's the issue.

> and caching and AI scraping complicate getting useful traffic data.
> Mermaid was proposed, and even GraphViz. (Personal note: I added
> support for Mermaid diagrams to https://git-scm.com/, but it turned
> out to be too limited, so I added GraphViz support. The support code
> for this is a bit of a beast, having a wasm version of GraphViz for
> development, pre-rendering the diagrams as SVG and as PDF during
> deployment of the site; it was quite a bit of fun to implement all
> that.)

Thanks for that! They don't look bad on the cheat sheet[4].

[4]: https://git-scm.com/cheat-sheet#combine-diverged-branches

-- 
Laters,
Toon