Bug #14313
Need balanced list of settings to include in each application's help and man page
| Status: | Needs More Information | Start date: | 05/04/2012 | |
|---|---|---|---|---|
| Priority: | Normal | Due date: | ||
| Assignee: |  Garrett Honeycutt | % Done: | 0% | |
| Category: | usability | |||
| Target version: | - | |||
| Affected Puppet version: | 2.7.14 | Branch: | ||
| Keywords: | ||||
Description
Any valid config setting is a valid option for the puppet command line applications. There are over two hundred settings. Even after adjusting for only settings that pertain to a given application, it’s not sane to print every potentially useful setting in the man page. Long term, we must fix this by reducing the number of settings.
In the meantime, each application should probably include some settings under its list of options. For the Faces apps, we’ll have a built-in way to pull in settings in Telly; for legacy apps, I don’t see any solution but manually pasting in the relevant settings.
These lists must include important settings, but must be limited enough that the man page doesn’t balloon out of control and become useless. Many useful but non-crucial settings will be left out of each man page.
History
#1
Updated by Kelsey Hightower about 1 year ago
Garrett,
After taking a brief tour of the related code, it seems that all of Puppet’s settings are available to all Faces as options. This is a big usability concern as it’s not possible to know all options valid for each Face. This sounds like a good question for UX; maybe we can work with them to come up with some possible suggestions on how we could improve this for our users.
In the meanwhile, maybe we can work with the doc team on some possible documentation improvements to make it more clear — there are hidden options available.
#2
Updated by Kelsey Hightower about 1 year ago
- Status changed from Unreviewed to Needs More Information
- Assignee set to Nick Fagerlund
Nick,
Is there anything we can do on the documentation front? Let me know how I can help.
#3
Updated by Nick Fagerlund about 1 year ago
- Subject changed from puppet agent usage does not mention --color argument to Need balanced list of settings to include in each application's help and man page
- Description updated (diff)
- Assignee changed from Nick Fagerlund to Garrett Honeycutt
I’m sick of playing whack-a-mole with these, so I’m changing the summary and description to reflect the real size of the task. Puppet agent can be the first one we try to fix.
Right now, puppet agent has the following “real” options:
- —debug
- —detailed-exitcodes
- —digest
- —disable
- —enable
- —fingerprint
- —help
- —logdest
- —no-client
- —serve
- —test
- —verbose
- —version
- —waitforcert
These are not settings. The man page also includes the following settings as options:
- —certname
- —daemonize
- —no-daemonize
- —noop
- —onetime
Garret, what should be added, and why? I am skeptical that color is important enough to make the cut, but can be convinced. Environment seems like a gimme, as does splay. I could see a case for tags.
#4
Updated by Garrett Honeycutt about 1 year ago
Glad that the root cause has been sorted out.
The --color argument is quite important to me, since that is what I initially created this ticket.
If you were to call the puppet agent in a script, it would output ANSI escape codes which makes reading or parsing the output quite difficult. Part of our Puppet Bootstrap’s often entail running puppet agent -t from a provisioning system as a post part of installation and the output needs to be legible.
#5
Updated by Garrett Honeycutt about 1 year ago
environment, splay and tags should all be in the docs. If it is a valid option, it should be in the docs. We should not have secret options.
Also, we teach environment and tags as options in the training.
#6
Updated by Nick Fagerlund about 1 year ago
Garrett Honeycutt wrote:
If it is a valid option, it should be in the docs. We should not have secret options.
Naaaaah, “valid” is a pointless distinction here; I’m asking what settings are relevant, which is a squishier metric. You can specify catalog_format on the command line, but no way am I allowing that in the man page. (And it’s not secret anyway; there’s a note in the man page pointing to the config reference, which has everything. That’s more than good enough for most of these; I just want the eight or nine for which it’s not good enough.)
Thanks for the note on what you teach in training, that helps.