Re: Rewriting the Git tutorial to cover less content
- From
Julia Evans <julia@jvns.ca>
- Date
- Sep 25, 2026, 19:22 UTC
- Message-ID
- <17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com>
- In-Reply-To
- <xmqqh5jdur4c.fsf@gitster.g>
On Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote:
Show 22 quoted lines
> "Julia Evans" <julia@jvns.ca> writes: > >>> See gittutorial(7) to get started, then see giteveryday(7) for >>> a useful minimum set of commands. >> >> This is a nice friendly statement, but in my opinion `gittutorial` and >> `giteveryday` really do not live up to what it promises, ... > > Yes, it outlived its time and the world has moved on. > >> I see a couple of possible strategies. >> >> * We can write new guides which are clearer >> * We can link to outside resources (via https://git-scm.com/learn) >> which we think do a good job. Right now that page is pretty >> out of date and it would be very easy to improve. >> >> I think a mix of both is probably most realistic right now. > > Whatever we do, it is not enough that new guides are more clear than > the current one. The goal should be that it also is sufficient to > replace the current one.
I don't understand what you mean by "replace the current one". Some interpretations I can imagine:
1. The documentation remains internally consistent, like if it says
"see <page> for <information>", then the information is in fact on that page
2. Any information explained in a guide must always be explained a
in some guide in the future
3. We should aim to make guides more _useful_ over time: on average,
a user reading the new version of the guide should come away having
learned more relevant-to-them information about Git than with the
old guide.
4. The original intent of a guide needs to be maintained.I imagine everyone agrees that #1 is important. I spend most of my time thinking about how to do a good job of #3.
> I do not know if we have bandwidth to keep external links fresh, and > having a set of links to stale pages ourselves may hurt more than > help.
We've had a list of links like this since 2013, at https://git-scm.com/doc/ext. It definitely has broken links and it would be pretty easy to update some of them once, which would help in the short term.