[NOTES 03/07] Documentation

[Taylor Blau <ttaylorr@openai.com>]

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.