Redesign Manual landing page

[jasonlong]

I'm hoping we can keep this simple and expose all of the man pages plus some useful jumping off links.

Placeholder here: https://git-scm-pr-1179.herokuapp.com/manual

[sxlijin]

We've got analytics floating around somewhere that I bet would be super helpful for this.

[jasonlong]

@sxlijin Yep, that's what I was thinking. According to Google Analytics, these are the most frequently visited man pages:

git-stash
gitignore
git-pull
git-checkout
git-merge
git-clone
git-rebase
git-commit
git-push
git-reset
git-diff
git-branch
git-fetch
git-show-branch
git-add
git-log
gittutorial
git-remote
git-submodule
git-init
git-clean
git-rm

Maybe we have a section with the most common commands needed for a basic workflow, something like:

git-init
git-clone
git-checkout
git-branch
git-add
git-commit
git-push
git-pull
git-merge

And then another with other frequently accessed pages like:

git-stash
gitignore
git-rebase
git-reset
git-diff
git-fetch
git-show-branch
git-log
gittutorial
git-remote
git-submodule
git-clean
git-rm

[sxlijin]

Hmmmm. Maybe it might make sense to categorize the commands?

I feel like in addition to basic workflow, rebase/reset/diff/log kinda fall into a "have a repo, trying to do X" category (and submodule/stash/fetch kinda fit here too).

Also worth noting, an alphabetic sort might be useful. Not sure if it's the best idea, but the first time I looked at that list I wasn't really sure how to browse it.

[jasonlong]

I started brainstorming ways of grouping the commands and kept coming back to the fact that we already have the commands organized in categories.

Here's another idea. We could expand out the existing categories w/ their one-line summaries (responsive version TBD) and then indicate the more popular pages with a star or something.

[peff]

I like that direction. You can still use the categories to find what you're looking for, or if you don't know the category, you can skim for stars.

It would probably make sense to keep the stars for each category grouped at the top, and probably make the non-starred ones smaller (e.g., by not including their one-line summaries).

[pedrorijo91]

just as @peff, I really like this version. But I would prefer to keep the one-line summaries in all the commands just for consistency. I think the star icon is enough to give the headlight

[peff]

My concern with the one-line summaries for all is just that it becomes hard to scan the list looking for "starred" entries. But I'm happy to punt on that until we see the final design and live with it for a while.

[jnavila]

Wouldn't the stars be more useful if put on categories where all the commands are common? Here it seems like despite their commonness, they are scattered in the page.

[jasonlong]

FWIW, based on the list from GA above, the most-frequented pages are indeed scattered over the page. I imagine this is from a mix of newer users looking at basic commands + more experienced users referring to harder to remember commands.

Edit: also, I'll be on vacation this week so there won't be much progress from my end until I'm back. 🌴

[sxlijin]

This kind of ties into an idea that's been bouncing around my head: it would be great to announce this somewhere and collect user feedback, e.g. /r/git, maybe /r/programming, lobste.rs, HN, etc., so that we have opinions from people who aren't Git contributors.

[peff]

I do think it's a good idea to get some outside feedback. I'm a little worried about having to sort through an influx of input with low signal/noise ratio (I don't mean to imply that the feedback will be low quality, but that we'll get a lot of "you should do this one specific thing" without very much overlap, some of which are bound to conflict, and sorting and organizing the suggestions will be a task in itself).

[dscho]

Since nobody has been working on thi, in over three years, maybe we should close this ticket?

Should someone show up willing to drive this improvement, we could easily reopen it.

[dscho]

Let's just close this.