Repository navigation
Define consistent scheme for Short command descriptions #1777
Description
Activity
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.
Reacted by samThis 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.
Reacted by samIf 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?Reacted by Sam Coe@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 :)
- Reacted by Mislav Marohnić and Amanda Pinsker
@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.
Describe the feature or problem you’d like to solve
The
Shortparameter used for commands is inconsistent and most do not provide any information beyond what is already provided through the name.gistis described asCreate gistsyet you can also view and edit gists,issuedescribes "managing" issues andrepolists the functionality supported.Proposed solution
Decide on a standard for the
Shortname.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
Shortdescription has high information density.Listing all of the commands supported could be automated (e.g:
Shortcould simply be a dynamic comma separated list) which would reduce the maintenance burden, however it might become unwieldy as new functionality is added --pralready 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
prsupportsreopenwhich provides an indication that status can be managed soreopen (+2 more)is as useful asreopen, 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
Curated List
Complete List
Additional 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.📄