why is the "user-manual" hidden?

[utonsal]

hello, the "user-manual" is stored in git-scm.com/docs/user-manual, but is not viewable when looking in the file git-scm.com/docs/ . Why is it 'hidden' in this way?

I read following notice about opening issues here, but on the git@vger.kernel.org -mailing list (which is referenced to from git-scm.com/community) , I was redirected here. "

• [ ] This is not an issue about
  • the Git documentation (a.k.a. man/help pages, i.e. anything with a URL starting with https://git-scm.com/docs), which should be raised with the community, "

greetings

[pedrorijo91]

Thanks for reporting this issue @utonsal :) The git-scm website is currently under a redesign work, so this can be addressed very soon.

What do you think @jasonlong ?

[jasonlong]

I’m out this week, but will take a closer look when I get back. My initial reaction was that I don’t immediately recognize this page and that we should definitely include it in the new top-level Manual section. On Tue, Mar 20, 2018 at 6:19 AM Pedro Rijo notifications@github.com wrote:

Thanks for reporting this issue @utonsal https://github.com/utonsal :) The git-scm website is currently under a redesign work, so this can be addressed very soon.

What do you think @jasonlong https://github.com/jasonlong ?

— You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub https://github.com/git/git-scm.com/issues/1188#issuecomment-374544991, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAX2Abl2GU_sQCZLiKWLS-BjORHt_gwks5tgNeYgaJpZM4Sxmmo .

[sxlijin]

Wow.

I just spent a few minutes digging for it, and what do you know - it's actually titled "Git's User Manual". It's mentioned briefly in the Description section of man git ("The Git User's Manual[1] has a more in-depth introduction"), and the pointer to it in the footnotes seems to be the only other mention.

In the Git repo, it's Documentation/user-manual.txt. It appears to largely date back to 2007.

Man, talk about RTFM. Thanks for bringing this to our attention @utonsal!

[peff]

I actually have mixed feelings about user-manual.txt. As you noted, it's pretty old. Most of that stuff hasn't changed, but I think that there are better resources these days. Like, say, the Pro Git content we already host, which is more comprehensive and accessible, has actual non-ascii-art diagrams, and is more actively maintained.

So I don't think it's wrong for us to host it or even link to it, but IMHO we should be steering people in search of a prose overview of Git to the book content.

[utonsal]

Am 23.03.2018 um 06:57 schrieb Jeff King:

I actually have mixed feelings about user-manual.txt. As you noted, it's pretty old. Most of that stuff hasn't changed, but I think that there are better resources these days. Like, say, the Pro Git content we already host, which is more comprehensive and accessible,

has actual non-ascii-art diagrams, which is a disadvantage, because less universal.

and is more actively maintained. which is a clear advantage.

There could also be the point, that the book is not considered free since it's license is CreativeCommons - Non-Commercial.

So I don't think it's wrong for us to host it or even link to it, but IMHO we should be steering people in search of a prose overview of Git to the book content.

greetings, utonsal

[jnavila]

has actual non-ascii-art diagrams, which is a disadvantage, because less universal.

It is your opinion that ascii-art diagrams are "more universal". Most of the time it's a bunch of characters that any non-seasoned reader will find ugly and incomprehensible.

[pedrorijo91]

added design label to be considered on #1179 cc @jasonlong

[prasadgujar]

@pedrorijo91 @jasonlong its this issue is still not resolved? if not I m interested in solving this issue.

[pedrorijo91]

I think it has been considered under the work in #1179 but not sure about the status

[utonsal]

very nice. As from what I see, my point is still not resolved, but rather has been talked away. utonsal

Am 06.03.2019 um 09:34 schrieb Prasad Mangesh Gujar:

@pedrorijo91 @jasonlong its this issue is still not resolved? if not I m interested in solving this issue.

[Vrihub]

Alas, still hidden in 2020. Even if it might not cover recent features, it's still a good medium-length introduction to git, that some users might prefer reading, before delving into the more comprehensive Pro Git book.

[peff]

@Vrihub My opinion now is pretty the same as from https://github.com/git/git-scm.com/issues/1188#issuecomment-375553433. If somebody feels strongly about it enough to make a PR, I wouldn't mind having a link from the /docs page. It probably needs some work in lib/tasks/index.rake to make it render properly, though. IIRC, the user-manual's asciidoc is unlike the regular manpages, so we may need some massaging of settings, etc, to get it to look right.

[jnavila]

says it all.

[dscho]

It's not really hidden, it's featured at the top of the git manual page.

And there is a very good reason not to feature it even more prominently: Git's user-manual is not actively maintained. Since this here ticket was opened over four years ago, it saw a scant 14 updates.

These updates mostly consist of additions, leaving the existing content unchanged.

However, the information provided there is seriously stale. I challenge you to verify that a fresh git.git clone still weighs a mere 40MB, or a clone of linux.git only 640MB. And this issue is just the tip of the tip of the iceberg of issues.

In other words, it is probably a very good idea to draw the curtain of charity over this user manual by actively avoiding to draw readers' eyes to it.

Having said all that, I could imagine one powerful counter-argument, and really only this one: This counter-argument would need to come in the form of a lengthy patch series on the Git mailing list that would improve, Documentation/user-manual.txt dramatically.

[dscho]

Let's just close this, there has no activity that would justify keeping this ticket open.