Add CLI UX principles to repo #1158
Conversation
|
@ryankeairns, thanks for your PR! By analyzing the annotation information on this pull request, we identified @adamhjk to be a potential reviewer |
Signed-off-by: Ryan Keairns <[email protected]>
ryankeairns
force-pushed
the
rk/ux-principles
branch
from
81cd996 to
280bee6
Compare
Signed-off-by: Ryan Keairns <[email protected]>
| - Don’t treat flags as 2nd class citizens. Be aware of existing flags and consider how they can/will be used across multiple commands and subcommands. | ||
| ### Make it Readable | ||
| - Familiarity, simplicity and readability make it memorable. Docs are useful, but we don’t want people having to continually refer back to them. | ||
| - Keep commands human readable and memorizable by using a sentence like structure `hab <noun> <verb>` |
There was a problem hiding this comment.
I'm not sure how it would fit with your headings, but it feels like this would be better placed near the top, to give people context on Habitat's use of nouns and verbs before they are described in other principles.
There was a problem hiding this comment.
Good call, moved that to top.
Signed-off-by: Ryan Keairns <[email protected]>
| ### Offer Timely Help | ||
| - Provide targeted/contextual help - make assumptions based upon their current setup (have they completed the install step?) | ||
| - Use flags to scope the help docs (normal/frequent, all, install, emergency) | ||
| - In times of emergency, provide a clear path to a human at Chef support (if possible) - remind of chef support email or phone number within help docs |
There was a problem hiding this comment.
Capitalize the second "chef" here, to be consistent with the first.
|
@ryankeairns this is wonderful!
|
| - Write output with a clear messages that a) sets the stage with “what we’re about to do”, b) progress “what is happening now”, and c) “did it fail or succeed?” and if it failed explain why, then provide a recommendation/next step. If it succeeds, celebrate it with memorable/playful message. | ||
| ### Expose Your Personality | ||
| - It’s a machine, but it doesn’t have to feel like one. Remind your users that there are people behind this product and that they care about your experience. | ||
| - Don’t overuse this principle by being overly silly or ever-present (that will be annoying), but a couple of inside jokes or playfully-worded sentences (especially during moments of success) sprinkled throughout keeps things interesting and personable (e.g. when a plan builds successfully out last line of output is “I love it when a plan.sh comes together.”) |
There was a problem hiding this comment.
"when a plan builds successfully out last line of output" reads a bit awkwardly.
Signed-off-by: Ryan Keairns <[email protected]>
|
I notice inconsistent punctuation with the bullet points. Some of them end with periods, and some do not. It's probably best to be consistent all the way through. |
|
Awesome docs Ryan!
|
Signed-off-by: Ryan Keairns <[email protected]>
|
@metadave @raskchanky thanks for the feedback! I've made edits to all comments and should be ready for 👍 when the test finishes. |
When making changes to the command line experience, contributors should consider these guidelines for commands and output.