Puppet users - Jun 2012 - UX/UI of puppet help when face actions have unmet dependencies

Hello,

We''re trying to come up with a nice way to indicate when a Puppet
module like cloud provisioner breaks a Puppet subcommand because of
missing dependencies.

When this happens in the current 3.0rc branch, all help for all
subcommands is unavailable.  This isn''t very helpful.

We''re planning to simply mark the subcommands that have incomplete
actions as unavailable.  Here''s a mock up of what we''re
thinking:

https://gist.github.com/3014923

Do you think the message, "check STDERR" in each of the node,
node_aws, and node_vmware subcommands is adequate?

The autoloader will catch and log the loading errors to STDERRO before
the help page is actually finished formatting, so the actual reason
the face failed to load will be presented before the formatted help
output.

Any feedback you have on making puppet help more helpful would be
greatly appreciated.

Thanks,
-Jeff

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Thu, Jun 28, 2012 at 5:37 PM, Jeff McCune <jeff@puppetlabs.com>
wrote:
>
> We''re trying to come up with a nice way to indicate when a Puppet
> module like cloud provisioner breaks a Puppet subcommand because of
> missing dependencies.
>
> When this happens in the current 3.0rc branch, all help for all
> subcommands is unavailable.  This isn''t very helpful.
Indeed, no.
> We''re planning to simply mark the subcommands that have incomplete
> actions as unavailable.  Here''s a mock up of what we''re
thinking:
It seems like you could also mark some as "partially available", if
some-but-not-all actions could be loaded.
> https://gist.github.com/3014923
>
> Do you think the message, "check STDERR" in each of the node,
> node_aws, and node_vmware subcommands is adequate?
No, mentioning STDERR is terrible UX, even if I know what it means. :)

I think a better approach would be to capture the error and report it
meaningfully.
> The autoloader will catch and log the loading errors to STDERRO before
> the help page is actually finished formatting, so the actual reason
> the face failed to load will be presented before the formatted help
> output.
As an interim measure, just reporting that the face (or action) failed
to load seems like a tolerable compromise - the root cause is clearly
indicated already, and mentioning STDERR doesn''t add much value.

Fixing the autoloader so that we can report meaningful errors rather
than having them hidden or just printed seems like a better long term
strategy, but is obviously more work. :)
> Any feedback you have on making puppet help more helpful would be
> greatly appreciated.
You should separate "unavailable subcommands" from "available
subcommands" entirely - display them in a distinct section of the help
output.

That obviates the need to add visual decoration, allows more space for
error display, and generally makes it clearer what is going on.

You should consider colour in this, as recent changes to UX include
colour highlights through the text - see the module tool for examples.

I think you should treat faces with some actions that failed
separately.  Perhaps call them out in this display, perhaps not, but
certainly treat them in the `puppet help node` style output as
"available actions" vs "unavailable actions".

-- 
Daniel Pittman
⎋ Puppet Labs Developer – http://puppetlabs.com
♲ Made with 100 percent post-consumer electrons

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Thu, Jun 28, 2012 at 8:00 PM, Daniel Pittman <daniel@puppetlabs.com>
wrote:
>> Do you think the message, "check STDERR" in each of the node,
>> node_aws, and node_vmware subcommands is adequate?
>
> No, mentioning STDERR is terrible UX, even if I know what it means. :)
>
> I think a better approach would be to capture the error and report it
> meaningfully.
The difficulty with this approach is that we''re currently relying on
Puppet::Util::Autoload#load_file [1] to load all of the face actions.
This method will catch and log the error from underneath the `puppet
help` implementation.

We''d have to change the exception handler quite a bit to make this
work.

[1]
https://github.com/puppetlabs/puppet/blob/3.0rc/lib/puppet/util/autoload.rb#L54-68
>> The autoloader will catch and log the loading errors to STDERR before
>> the help page is actually finished formatting, so the actual reason
>> the face failed to load will be presented before the formatted help
>> output.
>
> As an interim measure, just reporting that the face (or action) failed
> to load seems like a tolerable compromise - the root cause is clearly
> indicated already, and mentioning STDERR doesn''t add much value.
Our reason for mentioning STDERR is if the user is only capturing
STDOUT.  They wouldn''t see the error then, only that the subcommand
doesn''t have a summary available for some mysterious reason.
Mentioning STDERR gives the user a place to look for more information.

-Jeff

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Thu, Jun 28, 2012 at 8:00 PM, Daniel Pittman <daniel@puppetlabs.com>
wrote:
> No, mentioning STDERR is terrible UX, even if I know what it means. :)
>
> I think a better approach would be to capture the error and report it
> meaningfully.
The mockup does that, albeit before the rest of help output.  I think
we were too wedded to keeping errors on STDERR.  Including them again
in STDOUT below the help sounds better.
> You should separate "unavailable subcommands" from
"available
> subcommands" entirely - display them in a distinct section of the help
> output.
I disagree.  They should stay in the list and in alphabetical order so
that customers don''t have to look to hard for them.  That
doesn''t
obviate your (excellent) suggestion to include them below as well.
> You should consider colour in this, as recent changes to UX include
> colour highlights through the text - see the module tool for examples.
+1

r

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Fri, Jun 29, 2012 at 9:11 AM, Randall Hansen <randall@puppetlabs.com>
wrote:
> On Thu, Jun 28, 2012 at 8:00 PM, Daniel Pittman
<daniel@puppetlabs.com> wrote:
>
>> No, mentioning STDERR is terrible UX, even if I know what it means. :)
>>
>> I think a better approach would be to capture the error and report it
>> meaningfully.
>
> The mockup does that, albeit before the rest of help output.  I think
> we were too wedded to keeping errors on STDERR.  Including them again
> in STDOUT below the help sounds better.
Pieter is absolutely right that reporting errors on the output channel
is a bad habit in Puppet - it makes us wildly different to the Unix
standard.  Every normal application behaves the way we do now - errors
to stderr - and if the user isn''t looking, they have that same problem
with every other application too.
>> You should separate "unavailable subcommands" from
"available
>> subcommands" entirely - display them in a distinct section of the
help
>> output.
>
> I disagree.  They should stay in the list and in alphabetical order so
> that customers don''t have to look to hard for them.  That
doesn''t
> obviate your (excellent) suggestion to include them below as well.
So, perhaps the title of that should change from "available
subcommands" to "all subcommands" or something?

That was the key part that, to me, was worth making that change - that
these were absolutely *not* available, because they were broken.

-- 
Daniel Pittman
⎋ Puppet Labs Developer – http://puppetlabs.com
♲ Made with 100 percent post-consumer electrons

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Fri, Jun 29, 2012 at 10:22 AM, Daniel Pittman <daniel@puppetlabs.com>
wrote:
> So, perhaps the title of that should change from "available
> subcommands" to "all subcommands" or something?
>
> That was the key part that, to me, was worth making that change - that
> these were absolutely *not* available, because they were broken.
Probably we should instead say "Subcommands" or "Puppet
subcommands."

r

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

On Friday, June 29, 2012 at 1:22 PM, Daniel Pittman
wrote:
> Pieter is absolutely right that reporting errors on the output channel
> is a bad habit in Puppet - it makes us wildly different to the Unix
> standard. Every normal application behaves the way we do now - errors
> to stderr - and if the user isn''t looking, they have that same
problem
> with every other application too.
> 
> 

+1 to keeping errors on STDERR.  It would be my expectation as a sysadmin that I
could filter one from the other on output and I''d be fairly frustrated
if I couldn''t.

-- 

Eric Shamow
Professional Services
http://puppetlabs.com/
(c)631.871.6441
 

-- 
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To post to this group, send email to puppet-users@googlegroups.com.
To unsubscribe from this group, send email to
puppet-users+unsubscribe@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.