Remove gerunds and redundant prefixes from CLI command help text #13788
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
billpalombi
reviewed
Jun 5, 2024
There was a problem hiding this comment.
This is great, thank you!
I've proposed a few changes that go a bit further to standardize some of the terminology:
- Wherever there are two or fewer commands, just say those commands (e.g. "Serve and watch shell commands")
- Remove "Work with" entirely since its vague
- Reserve "Interact with" for things that are running (e.g. server, flow runs)
- Standardize on "Manage" for persistent objects (e.g. blocks, deployments, etc.)
docs/2.19.x/concepts/block--agent-based-deployments/deployments.mdx
Outdated
Show resolved
Hide resolved
Co-authored-by: Bill Palombi <bill@prefect.io>
|
Looking great! We should standardize on including periods everywhere or nowhere. I don't have a strong preference. I defer to you @djsauble |
billpalombi
approved these changes
Jun 6, 2024
chrisguidry
deleted the
rid_cli_commands_of_redundant_help_text_and_gerunds
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The default help output from the CLI has a lot of visual noise in the form of redundant "Commands for…" prefixes and gerunds.
We can make the help text easier to read by removing this verbiage.
We could take this even further by rewording the help text to do a better job of defining the concept itself instead of just mirroring the command in the help text (e.g. describing the "work-pool" command as "Commands for working with work pools" isn't very helpful, and we could make the help text more useful with a rewrite). That said, I'm not going to attempt this until I get more familiar with Prefect. :-)
Example
For example:
artifact Commands for starting and interacting with artifacts.…becomes…
artifact Start and interact with artifacts.Checklist
This pull request references any related issue by including "closes<link to issue>"If no issue exists and your change is not a small fix, please create an issue first.If this pull request adds new functionality, it includes unit tests that cover the changesmaintenance,fix,feature,enhancement,docs.For documentation changes:
This pull request includes redirect settings inmint.jsonfor files that are removed or renamed.For new functions or classes in the Python SDK:
This pull request includes helpful docstrings.If a new Python file was added, this pull request contains a stub page in the Python SDK docs and an entry indocs/mint.jsonnavigation.