[0.14] Update help text #26730
Merged
[0.14] Update help text #26730
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
This is just a husk of a container command that has no nested commands under it, so it isn't serving any purpose.
These are commands that either no longer do anything aside from emitting an error message or are just backward-compatibility aliases for other commands. This generalizes our previous situation where we were specifically hiding "internal-plugin", and does so in a way that fixes the long-standing cosmetic bug that the column width in the help output was chosen based on the hidden command "internal-plugin", which is unfortunately also the longest command in our command set.
A long time ago we introduced this separation between "common commands" and "all other commands", but over the intervening years we've not really done a good job of classifying new commands we've added and so by default most of them ended up being classified as "common". In the interests of making this output more useful for those getting started, this switches the two categories so that "Main commands" is now the curated list, and "all other commands" is the bucket for everything else. The intent here is that the "main commands" are the ones users are likely to try as part of their initial learning of Terraform, while the other commands are for less common situations where the user is more likely to learn about a specific command in some other context, like a tutorial about a special situation. The "main commands" are also now ordered by the sequence users will typically run them in, rather than alphabetical order. That's a subjective readability tradeoff, but I think as long as the list stays relatively short (which it should) it's still relatively easy to scan and find a particular command in the shortlist.
The short description of our commands (as shown in the main help output from "terraform") was previously very inconsistent, using different tense/mood for different commands. Some of the commands were also using some terminology choices inconsistent with how we currently talk about the related ideas in our documentation. Here I've tried to add some consistency by first rewriting them all in the imperative mood (except the ones that just are just subcommand groupings), and tweaking some of the terminology to hopefully gel better with how we present similar ideas in our recently-updated docs. While working on this I inevitably spotted some similar inconsistencies in the longer-form help output of some of the commands. I've not reviewed all of these for consistency, but I did update some where the wording was either left inconsstent with the short form changes I'd made or where the prose stood out to me as particularly inconsistent with our current usual documentation language style. All of this is subjective, so I expect we'll continue to tweak these over time as we continue to develop our documentation writing style based on user questions and feedback.
This just reduces the amount of space between different elements on in the main help output from four columns to two. The main motivation here was to give some of the longer command descriptions a little more horizontal breathing room, but subjectively I also find the tighter column gutters easier to scan. Others may disagree, of course.
My initial motivation here was to update the example output from Terraform's top-level help list to match recent updates in the layout and language used. However, while here I took the opportunity to update some dated language that was not consistent with our modern documentation writing style, in particular including a totally unnecessary and potentially-alienating claim that Terraform is "very easy to use". Our modern writing style discourages this sort of "boastful" language and encourages us to focus on the facts at hand.
pselle
force-pushed
the
pselle/help-text-0.14
branch
from
f6af66a to
d053e91
Compare
Codecov Report
|
|
I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further. |
ghost
locked as resolved and limited conversation to collaborators
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
Backport of #26695