Issue #7764 has been updated by Nick Fagerlund.
Okay, first off, this is way too much for one ticket, and it will be unusable
for the noise within another three posts, so our priority here is figuring out
what the larger issues/tasks/disagreements are and closing the ticket ASAP.
## Background
* The text blobs were all written BEFORE I had working templates, because
chickens. And eggs. It makes sense to give them another once-over once we have
a better idea of what help output should look like.
* Everything about the short templates is on the table, as far as I'm
concerned. Unlike man pages, there is no universal convention on how short help
should look. I expect there isn't an obvious sweet spot and we'll have to make
some tradeoffs.
## Issue one: the short help templates
I think I agree with having the first sentence of a description reiterate the
summary, removing the summaries from the short help templates, and removing the
copyright/license info from the short help. The examples, I could honestly go
either way on.
We have a continuum of usefulness that we're working within: terse is more
useful for experienced users who just need a reminder, wordy is more useful for
new users who need to learn. It sounds like Randall believes we should be as
terse as we can get away with, since we'll always have <del>Paris</del> the man
page. It sounds like Daniel is aiming for a spot more in the middle of the
continuum. I'm leaning more towards terse myself. I'll chop down the templates
tomorrow and see what it looks like.
## Issue two: inherited actions for indirector faces
Randall, it sounds like you think we should override every summary/description
for every indirector face, so we never get "retrieve an object" involved. I can
do that.
We've already talked offline about how we can't make the invalid actions
disappear. Daniel mentioned that some of the inaccessible actions won't stay
inaccessible forever. I don't have a firm idea of how to handle this in the
interim, but like Daniel said, we can't say save is invalid, because it's an
important part of the API, and the API needs documentation too.
## Issue three: API vs. CLI
In conclusion, arrrgh.
I think there are irreconcilable conflicts between the two goals. I am not
convinced that we can use the same text blobs to make really good API help and
really good CLI help. I believe this is going to eventually mean a lot of
duplication of effort.
* Return values are a problem here. Randall, sounds like you want returns to
describe the rendered output. For the API, that's useless; returns needs to
name the ruby object being returned. (Also, you mentioned "prints" vs.
"returns": I used prints when we use puts or the like to print to an IO handle,
and I used returns blobs when we actually return something. There's no
distinction on the CLI, but they're worlds apart in the API.)
*
## Issue four: default actions
Randall, based on things you've said here and elsewhere, it sounds like you
believe faces on which we set a default action should never be allowed to have
any additional actions. Is this the case, and if so, can you make a more
explicit UX argument for it? You've been letting that question go begged, and I
don't think there's consensus on it.
## Leftovers
I tried to make a list of actionable tasks from the non-controversial subset of
critiques:
- Introspect the render-as formats and display them in help templates.
- I consider this hard. Daniel might not.
- Some formats produce garbage for some actions. Is there a way to tell
which from the code? I put all that in notes.
- Remove copyright and license from short help
- Change "unknown" to "undocumented" in templates' fallback text
- Normalize format of description text (i.e. paraphrase or reiterate summary in
every description), including that in inherited indirector actions.
- Edit synopsis generator to ensure space between all option pairs (see
certificate sign for a run-together example)
- Edit plugin.rb's returns value to reinstate the info from
5120a95830183fdb30fc178452bfc3e6f44605b7.
- Edit resource_type to shorten the return values and move the long info into
notes.
- Collapse return value into one paragraph for config print.
- End all summaries with periods (see certificate find, among others)
- override inherited actions for catalog find, file search, others.
- Edit summary of catalog apply (match new behavior)
- Edit mode and terminus options in templates to fit on one line.
- Change short help templates to remove examples
- Standardize on "subcommand" instead of "face" in help text.
There are a few other questions about what people mean by things that I'll
follow up with in person later. I took notes. :)
----------------------------------------
Bug #7764: Many small issues with Faces CLI short help
https://projects.puppetlabs.com/issues/7764
Author: Randall Hansen
Status: Accepted
Priority: Normal
Assignee:
Category:
Target version: 2.7.0
Affected Puppet version:
Keywords:
Branch:
puppet help
* We should be consistent about using "subcommand" versus "face". I've been
thinking that we should use "subcommand" anywhere visible from the CLI, and
"face" only for the internal API. What do you think?
* Render format: what are the options? How do I find out?
* Does copyright need to take three lines? Can we put it all on one?
* The first sentence of the description is sometimes the summary, sometimes
similar to the summary, and sometimes different. We should make the call about
this and be consistent. My current best idea is to not show the summary.
* Some commands return "Examples" sections. I don't think we should do this,
but regardless we should be consistent.
* can we make the "--mode" option description live on 1 line? That would make
every help command look better.
* same for "--terminus"
* Some commands we have a "RETURNS" section. This should be consistent for
every command that returns data.
* E.g., `puppet help certificate_revocation_list info` says "Prints" when it
should have a RETURNS section.
* In fact, I kind of like it when it's blank (e.g., puppet help
certificate_revocation_list destroy)
* Some commands have options in USAGE that run together, e.g., USAGE: puppet
certificate sign [--terminus TERMINUS][--ca-location LOCATION]
* we should put a space between ][
* We should write a test that runs all help commands and looks for broken
things, like "invalid for this face"
* Some commands (perhaps all?) show the following for `... help save`: "Create
or overwrite an object. Save actions cannot currently be invoked from the
command line, and are for API use only."
* I don't understand this. Does it mean you can't used this "save" action at
all? If that's the case, we shouldn't expose it in the CLI help.
puppet help catalog
* Catalog:apply -- this help doesn't help me :) It's a more verbose way ot
saying it, but it doesn't define "catalog" or "apply".
* Catalog has two "destroy" actions (and non-helpful help for them).
* Catalog has two "search" actions (and non-helpful help for them).
puppet help catalog destroy
* this returns help, but it should return an error
puppet help catalog download
* doesn't seem to have help
* does show what seems to be boilerplate from secret_agent, which seems bad
puppet help catalog find
* no help, only description. is this enough?
* also, "name" in description but "<key>" in usage
puppet help catalog info
* help text is duplicated ("Prints the default terminus class for this face.")
puppet help catalog save
* help text is duplicated ("Create or overwrite an object.")
puppet help catalog search
* doesn't seem to have help
puppet help certificate
* find Retrieve a certificate # no period at end of sentence. We should
address this globally.
* save Invalid for this face. # should not appear
* search Invalid for this face. # should not appear
puppet help certificate destroy
* It would be nice to provide more guidance here. Tell them to use "cert"
instead? "Deletes a certificate. This action currently only works with a local
CA."
puppet help certificate list
* RETURNS section instead of description
puppet help certificate_request
* destroy Invalid for this face.
puppet help certificate_revocation_list
* save Invalid for this face.
* search Invalid for this face.
puppet help config print
* the RETURNS section is broken up, and it's not immediately clear that the
second paragraph is part of it
puppet help facts
* destroy Invalid for this face.
* search Query format unknown; potentially invalid for this face.
puppet help facts find
* What does this imply? RETURNS: A Puppet::Node::Facts object.
puppet help file
* destroy Invalid for this face.
* search Invalid for this face.
puppet help file download
* I don't understand the USAGE: USAGE: puppet file download [--terminus
TERMINUS] ( {md5}<checksum> | puppet:///... )
puppet help file key
* "key" seems like a weird name for this subcommand
* "Delete an object." is too brief. What object?
puppet help file key
* "Retrieve an object by name." is better, but still brief. What object?
puppet help file search
* "Search for an object or retrieve multiple objects." is too generic. This is
a common problem.
puppet help man & puppet help man man
* these should be the same. I don't imagine that's easy to do :)
puppet help node
* destroy Invalid for this face.
* save Invalid for this face.
* search Invalid for this face.
puppet help plugin download
* "RETURNS: A display-formatted list of the files downloaded. If all plugin
files were in sync, this list will be empty."
* Is it an empty list, or no return at all?
puppet help report
* destroy Invalid for this face.
* find Invalid for this face.
* search Invalid for this face.
puppet help report submit
* This action is essentially a shortcut and wrapper for the `save` action
with the `rest` terminus, which provides additional details in the
event of a report submission failure. It is not intended for use from
a command line.
* If something's not usable from the CLI, we shouldn't be exposing it in CLI
help.
puppet help resource
* destroy Invalid for this face.
puppet help resource find
* RETURNS: A resource object.
* We should be consistent about this. Some places we give the full Ruby
object name, some places we give the more generic name. In either case we
should provide more context about what "object" means.
puppet help resource search
* RETURNS: An array of resource objects.
* how is it formatted? should we provide formatting advice?
puppet help resource_type
* destroy Invalid for this face.
* save Invalid for this face.
puppet help resource_type find
* this is huge help. Are all the details necessary?
puppet help resource_type search
* RETURNS: An array of resource collection info hashes. (See "RETURNS" under
`find`.)
* s/`find`/`puppet help resource_type find`/
--
You have received this notification because you have either subscribed to it,
or are involved in it.
To change your notification preferences, please click here:
http://projects.puppetlabs.com/my/account
--
You received this message because you are subscribed to the Google Groups
"Puppet Bugs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/puppet-bugs?hl=en.
