Improve desc

[ako80218]

Hello,
During a recent Wordpress contributor day in Denver, a team of us worked to improve documentation, both inline in the PHP command files and on the commands page at https://developer.wordpress.org/cli/commands/. Specifically, we tried to author better descriptions for the commands, aiming to have the same description appear in both places. This is my first of several pull requests. Each request will offer a revised description authored within the appropriate command repo. I wanted to see how this first request goes before issuing several more of them. Please let me know if you have any questions.

Thanks!

[danielbachhuber]

The short description needs to be 80 characters or less, so I think it makes sense to drop the link.

Instead, the link can go in the extended description (next blog of text) as a markdown link (so it renders as a link on the website).

Is there a rephrasing "The cache command manipulates the WP Object Cache." so that we don't start every command description with "The" ?

[gitlost]

I wanted to see how this first request goes before issuing several more of them

I think it would be better to deal with them not initially as individual pull requests but all at once at wp-cli/wp-cli#4302, so a uniform approach and style can be arrived at.

The short description needs to be 80 characters or less

That's just a "soft" requirement though, isn't it, there's nothing technical-wise stopping the short description being longer (is there?), though obviously it should be brief. (The problem with the original PR #7 wasn't the length as such but the newlines.)

[danielbachhuber]

I think it would be better to deal with them not initially as individual pull requests but all at once

But they're in separate repos?

[gitlost]

Just the discussion first at wp-cli/wp-cli#4302 I'm thinking, the pull requests to follow...

[ako80218]

Hey all,

As it is right now, many of the revised descriptions exist in separate repos. I still have some descriptions to revise. I'm happy to consolidate into one repo (i.e. wp-cli ) and make one pull request if that is better. As for a uniform style, I propose a "command-name does this" approach where the command name is the first word of the description rather than "The". Finally, I am trying to read into the code to understand better how the short description gets clipped by a new line as well as the 80 character soft requirement. Could I get some rough guidance on where to look in the code as well as how I should for a uniform approach and style for the descriptions? Thanks!

[gitlost]

I didn't mean to confuse things, let the discussion take place here!

the command name is the first word of the description rather than "The".

I think the command name is implied, and neither it nor "The" is necessary.

how the short description gets clipped by a new line

See https://github.com/wp-cli/wp-cli/blob/master/php/WP_CLI/DocParser.php#L47 - the short description is parsed until the first newline (and any subsequent contiguous ones). So the short description is a one-liner.

get some rough guidance on where to look in the code as well as how I should for a uniform approach and style for the descriptions

I think it's all up for grabs. Some commands have good descriptions, some have the "Manage XXX". As I mentioned in wp-cli/wp-cli#4302 (comment) I like the style of wp cli

Review current WP-CLI info, check for updates, or see defined aliases.

[ako80218]

Many thanks @gitlost. I will study DocParser.php and I can use the wp cli description as a template for the approach and style.

[danielbachhuber]

Closing this for now.

@ako80218 Feel free to suggest command descriptions in wp-cli/wp-cli#4302 and then we can create pull requests once we've chosen.