Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

why is the "user-manual" hidden? #1188

Closed
1 task
utonsal opened this issue Mar 20, 2018 · 15 comments
Closed
1 task

why is the "user-manual" hidden? #1188

utonsal opened this issue Mar 20, 2018 · 15 comments
Labels

Comments

@utonsal
Copy link

utonsal commented Mar 20, 2018

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 [email protected] -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
Copy link
Member

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
Copy link
Member

jasonlong commented Mar 22, 2018 via email

@sxlijin
Copy link
Contributor

sxlijin commented Mar 23, 2018

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
Copy link
Member

peff commented Mar 23, 2018

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
Copy link
Author

utonsal commented Mar 23, 2018 via email

@jnavila
Copy link
Contributor

jnavila commented Apr 12, 2018

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
Copy link
Member

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

@prasadgujar
Copy link

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

@pedrorijo91
Copy link
Member

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

@utonsal
Copy link
Author

utonsal commented Mar 14, 2019 via email

@Vrihub
Copy link

Vrihub commented Dec 2, 2020

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
Copy link
Member

peff commented Dec 2, 2020

@Vrihub My opinion now is pretty the same as from #1188 (comment). 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
Copy link
Contributor

jnavila commented Dec 2, 2020

image

says it all.

@dscho
Copy link
Member

dscho commented Sep 28, 2024

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
Copy link
Member

dscho commented Oct 25, 2024

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

@dscho dscho closed this as not planned Won't fix, can't repro, duplicate, stale Oct 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

9 participants