Re: Rewriting the Git tutorial to cover less content

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

>> Dealing with broken links is easier as we can just remove them.
>> Noticing a link that points at an unmaintained stale document that
>> describes what used to be relevant but no longer in today's
>> environment and replacing it with something more relevant was what I
>> am worried about.
>
> Thanks, this is helpful. Let me try to rephrase to see if I understand,
> let me know if I'm understanding wrong.

In the above, I was talking about the reference links that are stale
at https://git-scm.com/doc/ext which you mentioned.  You said that
it is easy to update broken links there.  I wanted to point out that
there are two kinds of staleness, one that you can validate by
clicking on the link and seeing 404 (your "easy" kind), and the
other that you have to read what you are given by clicking on the
link and evaluate its relevance in today's world (which is much
harder).

So, while I do agree with everything you said in the two paragraphs
below, I do not think these two paragraphs have any rephrased
version of what I wanted to say ?-).

> When possible, it's better to split up changes into smaller pieces so
> that they can be reviewed more easily.
>
> For this change, it would help to split it up into two different patch series:
> "remove tutorial" and "add new tutorial", where the first patch series
> deletes all references to the tutorial. If we do it this way, we can
> both make sure that there isn't any content that we regret deleting,
> and lets us take a look at the documents that reference the tutorial too.

Yes, feeding smaller independent pieces is a format that is easier
to review.  If the end result is that the old tutorial is gone and
replaced by the new tutorial, that would be what we want.  When we
added gittutorial-2, we did not remove gittutorial, probably because
nobody had the guts to say "let's rip out what Linus wrote, it is so
out of date and gives much less relevant information useful in
today's world".

I do not want to repeat that; it is like https://xkcd.com/927/.