Style guide - Successful, failure, error states

[jeffandersen]

Talking points

• Complex error messages
  • Error message plus description
• Successful states contain output or not?
  • In a lot of system tools no output is the success state
  • Most of our commands now provide a confirmation message
• Invalid usage? validation failure?

[jeffandersen]

We should always lead a complex error message with a sane/friendly explanation, followed by the more technical output (which can be helpful to power users, and useful in debugging).

We should never panic, that's a bug.

In a lot of cases our command output infer context from their cwd. Because of this I feel that every command should have a success or failure message that shows the result of this. For instance, showing the path that has been computed, or showing which object has been created. We're much more of a product that just a command line utility, so I don't think that it's too unexpected.

[ntassone]

+1 to utilizing context where possible.

I'm in favor of having success states contain output but I'm coming at this from a non-programmer background. Are success messages considered extraneous to the average programmer? Confirmation seems more considered.

[ntassone]

Another topic we talked about was empty states.

I think we should utilize the hints ui in our empty states to suggest the user can perform an action in order to make the state non-empty. Example:

$ torus services list

Project 'www' has no services. 
* Create a new service by running 'torus services create'