From: Taylor Blau Date: Tue, 06 Oct 2026 18:06:21 GMT Subject: [NOTES 03/07] Documentation Message-ID: In-Reply-To: Topic: Documentation * Julia: There is a big gap between contributors who know Git's concepts and users who do not know what objects or the index are. I have been working on a website to bridge that gap. We do not explain some basic terms, such as "upstream". Some documentation receives hundreds of comments. How can we bring that feedback to the mailing list without overwhelming it, and improve the documentation with very little funding? * Patrick: Could we expand the funding? This work is important, and we are not technical writers. * brian: We have gitglossary and the Pro Git book, but it would be good to have beginner documentation. Many users arrive from university without knowing these concepts. I have submitted some documentation in this area. * Patrick: Pro Git may be outdated in places. Scott wants a new version and could fund somebody to work on it. * Emily: We can suggest a huge book to somebody who is new and just wants to use Git. * Peff: The manpages are reference material, so they should be terse. Most users also need something less terse. If somebody is interested in working on this, we should consider replacing outdated documentation rather than preserving it for its own sake. * Patrick: We should allow iterative work. Review can be nitpicky, but perhaps we can be more accommodating so this can move faster. * Julia: Being able to merge quickly and iterate would help. Mailing-list feedback is useful. * brian: Thank you for working on the documentation. Bad documentation, or no documentation, makes software hard to use. * Patrick: Terse does not necessarily mean accessible. We could learn from TLDR and include examples. * Julia: Examples are useful, and we should update the existing ones. * Josh: We could consider Diataxis, which separates tutorials, guides, explanations, and reference material: https://diataxis.fr/ * Julia: The format of the reference manpages makes sense. * Peff: I did not mean to defend the manpages. New-user documentation and manpages are two separate things, and both need work. * Julia: Git has guides and manpages, which is a useful separation. The guides are harder to discover; the manpages are more accessible. * Patrick: How much time do you have funding for? * Julia: We have 100 hours split between two people. * Patrick and others: Perhaps we could use the Git fund. * Peff: Other companies might also be interested in funding the work. * [OpenAI, GitHub, and GitButler were mentioned as possibilities.] * brian / Emily / Mark: We can ask about funding. * Mark: We have both machine-readable and human-readable material. * Toon: We are only discussing written documentation. * Peff: Costs can escalate with video. I am biased toward written documentation. * Patrick: GitButler has resources, and younger users may prefer videos. * Julia: We could link good Git videos from the website. * Emily: There are links on Discord that we could include. * Julia: We do not have a good entry point on the Git website explaining how to learn Git. * Peff: The site had one, but it gets outdated. We should refresh it as we go. * Julia: Some documentation says "see section XYZ" without linking it. We cannot link to subsections of manpages. * Peff: I spent some time generating subsection links. * Julia: We have links to other pages, but not to subsections. * Peff: References in the text need the linkgit markup. This could be an incremental project. * Julia: I added a cheatsheet to the website. Do we want to move away from ASCII diagrams? * Patrick: Could we use different sources for different outputs, with SVG for HTML and ASCII for manpages? * brian: We could do that. * Patrick: Perhaps Mermaid would let us keep a plain-text source and choose the output format. * Julia: It should be possible. We have CI scripts that Johannes worked on, and we used Graphviz. * brian: There are extensions, but they are not packaged for distributions. * Peff: We support both AsciiDoc and Asciidoctor. Would it help to get out of that dual world? * Patrick: Traditionally this was for migration. AsciiDoc was thought to be unmaintained, but it is maintained now. * Peff: We could move to Asciidoctor. * brian: Fedora still uses AsciiDoc. Asciidoctor is well maintained, written in Ruby, and reasonably portable. It depends on how much we want to support. I do not know whether Fedora is still an obstacle. * Peff: Who would object to moving, and how strongly? * Junio: We could include it in Git 3.0 and add it to BreakingChanges. * Josh: Some documentation already renders poorly with old versions of AsciiDoc. * Peff: Send those bugs to the list; somebody may be interested in fixing them. * Josh: We could use this to fix the build pipeline and move away from AsciiDoc. * Patrick: Fedora does have Asciidoctor, version 2.0.26. * Peff: I tried Asciidoctor on Debian, and it works well. There are some rendering issues, though it mostly gets things right. Julia, would you be interested in using doc-diff to compare the outputs? * [Patrick created an issue during the discussion.] * Emily: Do we have traffic metrics for git-scm.com? * Taylor: Some high-level metrics in Cloudflare. * Peff: We had Google Analytics, but were not comfortable with it and removed it. * Emily: It would be useful to know how many users read the documentation. * brian: It would be useful to know which manpages people read, while being mindful of privacy as an open-source project. * Taylor: Could we self-host metrics, or use a third party that supports this? * Mark: Fathom is one privacy-focused option: https://usefathom.com/ * brian: Even webserver logs would be useful for getting some numbers. * Peff: On Heroku, the caching layer meant we did not see accurate numbers. * Patrick: Will AI scrapers drown out the useful signal? * Toon: I opened an issue about this some time ago: https://github.com/git/git-scm.com/issues/2054 * Taylor: We enabled it, but did not see useful information.