Open jeffandersen opened 7 years ago
We can use this issue to talk a bit about our philosophy and approach to general layout of the tool.
Some inspiration and resources:
Do
, Consider
, Avoid
etcWe had a good discussion about this IRL last week. Didn't get into specifics as much as general philosophy but a good kick off for discussion.
To start the discussion here, I'll make some reaches as to how I think the points above should be addressed and go from there:
Arguments are passed into options so that doesn't really warrant much discussion, I'll just talk about options for the time being.
These are currently being referred to in the documentation as both options
and flags
. In the code they're referred to as flags
(for the most part). To keep it consistent and for simplicity's sake, we should call them options
when referring to both global/command options.
Options should be in the format of two dashes with one phrase after: --option
. In the case of a multi word phrase, words should be separated by a dash: --multi-word
. Each option should contain a sensible lowercase, one character, shortcut version like -o
for --option
.
The general guide to naming a command should be to make it as simple and relevant as possible. When writing a description of the command for help, or in a hint (!), I think we add to the style guide that being concise is key. We have documentation where you can expand and explain more verbosely.
Should consistently be in Future I Simple – basically will without actually saying will. torus profile
will Manage your Torus account. Don't restate the command. Example:
Correct
torus profile: Manage your Torus account
torus send: Send an invitation to join an organization to an email address
Incorrect
torus profile: Profile manages your Torus account
(restates and wrong tense)torus send: Sent and invite to join
(wrong tense)I don't think we can assign too many rules to plurality. As long as you are consistent, plurality will change on a case by case basis.
For example, it makes sense for torus invites
to be plural because invite
would infer a verb, like torus invite <user>
. However, the help for invites
mixes the words invites
with invitations
when describing invitations
. Using invitations
in the descriptive text and only using invites
when referring to the command would help make the help more clear.
To reduce fragmentation in our CLI and to improve some of the interactions we use, we are going to produce a style guide.
This issue will act as a central hub for all things style guide, which will start with discussion around each major area of input/output.