Re: Rewriting the Git tutorial to cover less content

["Julia Evans" <julia@jvns.ca>]

On Fri, Sep 25, 2026, at 2:23 PM, Junio C Hamano wrote:
> "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.