Update gh help output - #815

This is an update to the help documentation based on ideas from @ampinsk (https://github.slack.com/archives/CLU79NDAS/p1587488768040500).

Before

After

Technical issue

I was hoping I could do more with Cobra to make the help documentation more automatic. For example, if I could add metadata to commands then separating “core” and "additional" commands would be possible with cmd.SetHelpTemplate. Unfortunately, without some extreme hacking to our commands I couldn't figure out a way to make that possible. But I don't think this is something to worry about because this code is still mostly generated via commands and now all the help documentation is in one place making it easier to edit in the future

Responses to comments

“commands are run inside of a GitHub repository”: as you pointed out in another thread, this isn't always true. it won't be true for some gh repo create, some gh repo fork, and usually for gh repo clone. it also isn't true for any use of gh -R owner/repo, nor for gh config, nor will it be true for gh api when a direct API access command lands. so I'd avoid stating this as some kind of rule. maybe somewhere in the lower description we can say something like "it makes sense to run most commands from the directory of a local git repository.”

I tried to address this with the line "most gh commands need to be run in a directory containing a GitHub repository." But maybe the user would benefit more if our commands have a better error when they are run in a directory without a repository.

5. “read the manual at”: they’re already reading the manual! the whole point of having the manual at their fingertips on the command-line is so that they don’t have to go elsewhere to read the documentation. also, the online manual will not necessarily match their installed version of gh. I strongly feel that we should not link to the manual elsewhere.

We differ on this point. The help output is very high-level so I don’t see it as the manual for the app. I go the web to read documentation and see example usage for commands like find and grep because I find it easier to read than text on the terminal. I see including this as a way to make web documentation discoverable to people who might benefit from it.

Closes #711