git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: Rewriting the Git tutorial to cover less content

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 25, 2026, 19:34 UTC
Message-ID
<xmqqv77tt9a4.fsf@gitster.g>
In-Reply-To
<17c46e4e-a4f6-433e-8eea-c1e4eb28fdfd@app.fastmail.com>
"Julia Evans" <julia@jvns.ca> writes:
> I don't understand what you mean by "replace the current one". 

If giteveryday for example is so stale and unusable, we should drop the entire file. If there were some topics in there that can be salvagd, we should freshly explain these topics elsewhere in our documentation, and starting a new document is one way to do so. Then we "replaced" the current "giteveryday" with something else.

Show 11 quoted lines
> 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.
Show 7 quoted lines
>> 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.

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.

Previous: Julia EvansNext: Julia Evans
Message 21 of 23 in “doc: add more AsciiDoc cross-references”
  1. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 22, 2026
  2. Junio C HamanoSep 22, 2026
  3. Julia EvansSep 22, 2026
  4. Jeff KingSep 23, 2026
  5. Julia EvansSep 24, 2026
  6. Jeff KingSep 24, 2026
  7. Junio C HamanoSep 24, 2026
  8. Julia EvansSep 24, 2026
  9. Junio C HamanoSep 24, 2026
  10. Jeff KingSep 24, 2026
  11. Jean-Noël AVILAOct 18, 2026
  12. Kristoffer HaugsbakkSep 23, 2026
  13. Jeff KingSep 23, 2026
  14. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 25, 2026
  15. Jeff KingSep 25, 2026
  16. Rewriting the Git tutorial to cover less contentJulia Evans, Sep 25, 2026
  17. Junio C HamanoSep 25, 2026
  18. Julia EvansSep 25, 2026
  19. Junio C HamanoSep 25, 2026
  20. Julia EvansSep 25, 2026
  21. Junio C HamanoSep 25, 2026
  22. Julia EvansSep 28, 2026
  23. Junio C HamanoSep 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.