Repository navigation
Define consistent scheme for Short command descriptions #1777
Description
Describe the feature or problem you’d like to solve
The Short parameter used for commands is inconsistent and most do not provide any information beyond what is already provided through the name.
CORE COMMANDS
gist: Create gists
issue: Manage issues
pr: Manage pull requests
release: Manage GitHub releases
repo: Create, clone, fork, and view repositoriesgist is described as Create gists yet you can also view and edit gists,issue describes "managing" issues and repo lists the functionality supported.
Proposed solution
Decide on a standard for the Short name.
I think there's a few different options, each of which has pros and cons. The conclusion I've come to is that because the CLI is typically used by power-users ("Goodbye, context switching.") that the best Short description has high information density.
Listing all of the commands supported could be automated (e.g: Short could simply be a dynamic comma separated list) which would reduce the maintenance burden, however it might become unwieldy as new functionality is added -- pr already has 12 supported commands.
Another option could be to pick a subset of the commands that provide enough context to inform the user about the depth of support, for example pr supports reopen which provides an indication that status can be managed so reopen (+2 more) is as useful as reopen, close and ready.
Another option could be to describe the resources as products/features: I don't think that provides as much value to power-users, but as the CLI functionality expands and new product lines are introduced it might become more valuable -- if I didn't know what a gist is, I'd benefit from this approach.
Product Description
CORE COMMANDS
gist: Share content privately or publicly
issue: Keep track of tasks within your team
pr: Participate in living conversations about changes
release: Package software for people to use
repo: Keep and collaborate on code with GitHubCurated List
CORE COMMANDS
gist: create, edit, list and view Gists
issue: create, list and close Issues (+3 more)
pr: create, review and merge Pull Requests (+9 more)
release: create, download and view Releases (+3 more)
repo: clone, create, fork and view RepositoriesComplete List
CORE COMMANDS
gist: create, edit, list and view
issue: close, create, list, reopen, status and view
pr: checkout, checks, close, create, diff, list, merge, ready, reopen, review, status and view
release: create, delete, download, list, upload and view
repo: clone, create, fork and viewAdditional context
Definitely not a big issue, just some polish! I'm happy to PR any changes that are agreed upon: creating an issue first for discussion per the contribution guidelines. After working through this issue I've decided I like the curated list ((+n more) option) most.
📄
Activity
mislav commentedon Sep 18, 2020
Great suggestion! Thank you
/cc @ampinsk
vilmibm commentedon Sep 18, 2020
oh, I really like that first option to describe the product. I think listing out subcommands makes sense but is redundant with the help page for an individual command; the product description feels a lot more "gh" style to me in its human friendliness.
ampinsk commentedon Sep 18, 2020
This is a great writeup, thank you @shrink! I really like the idea of the product description, but I do think the CLI is pretty unlikely to be your very first introduction to GitHub, so explaining what these products are here might not be that useful. That said, a pro here is that we wouldn't need to update these, and I do like the human friendliness.
Of these, I think my favorite is also the Curated List option. It might be redundant with the interior help pages, but I like being able to give a peek at the top level into what the subcommands are (and that they exist/are often required!). The biggest con here though is that we'd need to update these every time we added a new command, so it's likely these will fall out of date again unless we figure out a way to automate it.
oracle3987 commentedon Sep 22, 2020
ampinsk commentedon Sep 24, 2020
If nobody has any other input or thoughts here, do we want to go ahead with Curated List? Is there a way to automate the
+3 morepiece of this?shrink commentedon Sep 24, 2020
@ampinsk I'm happy to put together a PR with the Curated List option (including the automated counter) if that would be helpful as a way for people to get a better idea of how it'll feel in practice -- even if Curated List isn't chosen in the end, I don't mind if the code is thrown away :)
shrink commentedon Sep 24, 2020
@ampinsk Hi! I created a PR for the Curated List behaviour -- #1952 -- and I've left it in Draft so it isn't merged without your review. People should be able to run that locally and see how it would behave in practice. No worries if you don't choose this approach, it was a fun exercise.
mislav commentedon Sep 28, 2020
@shrink Thanks for proposing this and prototyping an approach to implementing this!
Now that I see how it all plays out, I got to say I'm not a fan of the
+N morerendering. It feels weird to see it without an easy way to "expand" the+N morepart to see what's behind it.I do not believe that we need to explicitly list every single operation under an object such as
issueorpr. The way I see it, "manage issues" is descriptive enough a summary to give people an idea of what's under there, and then the user can dogh help issueto find out more.