wp help <specific-command> should be mentioned earlier / more prominent in help index

[porg]

1) A meta question

I wanted to submit a change to the output of purely wp itself (aka "help index" aka "manpage index"). Which file(s) are used to build this? The content which starts like:

NAME

  wp

DESCRIPTION

  Manage WordPress through the command-line.

SYNOPSIS

  wp <command>

SUBCOMMANDS

  ...

Did a full text search for Manage WordPress through the command-line in both https://github.com/wp-cli/handbook and https://github.com/wp-cli/wp-cli but found nothing. I had wanted to submit a change to this as a pull request. But as I was not able to find the source for this, I put my proposal here itself.

2) The change proposal itself

In the section "SUBCOMMANDS" the help command itself is summarized like this:

help                  Gets help on WP-CLI, or on a specific command.

And only at the very end you have:

Run 'wp help <command>' to get more information on a specific command.

This is not so ideal. I propose to do one of the following:

a) Amend the SYNOPSIS section.

SYNOPSIS
   wp <command>
   wp help <specific-command>

b) Or in the SUBCOMMANDS section change the help command:

help           Gets general help on WP-CLI. What you are currently reading.
help <cmd>     Gets help on a specific <cmd> in WP-CLI.

I even would propose to except those from the alphabetical order and put them first, with one empty line inbetween, as they are serve as a quick lookup from more specific help.

[danielbachhuber]

Thanks for the suggestion, @porg

1. A meta question

Good question, it's definitely not obvious.

All of the help docs are produced by Help_Command and the functions it calls: https://github.com/wp-cli/wp-cli/blob/d99e2532014d3e0d14999b5f1e4382d9420c8aea/php/commands/src/Help_Command.php

2. The change proposal itself

I'm not sure amending the SYNOPSIS is quite the right place. The SYNOPSIS is meant for the command itself.

I agree that the current location of the text is a bit hidden.

We could potentially inject it at the top of the SUBCOMMANDS section:

Or potentially inject a HELP section to this root doc.

It might be useful to see how other popular CLI tools expose their --help feature.

[porg]

Ok then

• not in the 1) SYNOPSIS section, I agree with that, had expressed doubts myself.
• but 2) in the SUBCOMMANDS section on the very top. With a blank line after them, to make clear that the other subcommands are then alphabetically ordered.

Best practise for CLI help screens and how they mention help itself

• Just ran --help for a random choice of CLI apps, which I recently used
• The best practise is very clear from my sample of 5 CLI --help screens:
  • Most of them mention help very early on (highlighted in blue, git is the exception)
  • And many of them also give info how to use help command itself (git otherwise the exception, also does this)

Screenshot with 5 CLI --help screens

[danielbachhuber]

Those examples are helpful, thank you.

Few more ideas to throw into the mix:

• Include a GETTING STARTED section for wp that provides 1-3 paragraphs about WP-CLI with basic usage instructions.
• Include a HELP section for wp that's more specifically focused on getting help (e.g. running wp <help>, asking for help in #cli on Slack, etc.)
• Moving GLOBAL PARAMETERS above SUBCOMMANDS, or somehow highlighting "important" global parameters.

I'd be curious to hear other opinions from @wp-cli/committers

[schlessera]

Two thoughts on this:

• We often have a conflict between surfacing as much help as possible and being efficient with screenspace for power users. That's why we have an environment variable to disable the global flags, for example.
• The tail of the output is what remains on the screen if the entire output does not fit. So starting with the help at the beginning would mean it is the first information that gets scrolled out of view.

I'm not against improving on this, just wanted to mention that there are several conflicting goals we're trying to solve for here.