From: Julia Evans Date: Fri, 25 Sep 2026 19:22:29 GMT Subject: Re: Rewriting the Git tutorial to cover less content Message-ID: <17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com> In-Reply-To: On Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote: > "Julia Evans" 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 for ", 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.