Write Useful Messages

It’s never too early to start thinking about the messages you display for your users. Messages include:

• Required summaries for every command and flag
• Optional longer descriptions for commands or flags
• Examples
• Error messages
• Interactive prompts

While you're free to write your messages in any style you want, we recommend that you follow these writing guidelines so that your commands feel similar to the core Salesforce CLI commands.

Implement Messages

TBD. Bullet points:

• diff between --help and -h
• markdown files in messages dir
• h1 for message name. List our conventions for naming (summary, flags.<name>.summary, etc). Not necessary, but conventions are nice.
• examples:
  • to nicely render, use "-" for explanation and then indent with two spaces
  • use <%= config.bin %> <%= command.id %>
• errors:
  • errors/warning/info messages are pre-pended at runtime with Error: , etc.
  • Nice to have an action.
• package.json: topic descriptions

Writing Guidelines

These writing guidelines ensure that the CLI messages for all commands are similar in style.

Commands

Use clear, concise descriptions so that users can easily understand what your commands do.

Summary

• Summaries start with an imperative verb.
  • For example, a good summary for the sf deploy metadata command is Deploy metadata to an org from your local project.
• Summaries are mandatory for each command.
• The summary is the first message that displays when users run --help or -h for a specific command. The summary is also displayed as the first sentence in the DESCRIPTION section when using --help. It's also the message that’s displayed when using --help to list a group of commands.
• Summaries include just enough information to tell users what the command helps them do, but are as short as possible.
• Summaries use proper punctuation and capitalization and are complete sentences.

Description

• Command descriptions are optional but highly encouraged. They are displayed in the --help output, but not the -h output.
• Write them to expand on the summary, provide context about how and when a user runs the command, describe the behavior of the command, and provide other helpful information for the user. Here are some questions to help you pinpoint this other helpful information; not all questions are relevant to all commands.
  • Where does this command fit in a typical developer workflow? Would it help the user to know which commands are typically run before or after?
  • What, if any, are the repercussions of using this command? Is the command destructive? For example, does the command overwrite files in an org? Overwrite local files?
  • Does the command behave unexpectedly when a user specifies a particular combination of flags?
  • Is the command output easy to read, or is it complex enough that you should describe how to interpret it?
  • Is there an operating system-specific gotcha? For example, do Windows users need to use quotes to enclose a value when macOS users don’t?
  • Is there another command that the user might confuse with this one? Do you need to describe the use cases for each command?
• While there’s no theoretical limit to the length of a long description, try to keep it brief yet comprehensive.
• Long descriptions use proper punctuation and capitalization and are complete sentences.

Flags

Use clear, concise descriptions so that users can easily understand what the command flags do.

Summary

• Flag summaries are mandatory for each flag. They are displayed in tabular form in the top FLAGS section of both the --help and -h output.
• Flag summaries include just enough information to tell users what the flag does, but are as short as possible to minimize wrapping in narrow terminals.
• For flags that accept a value, the summary describes the value that the user supplies.
  • For example, a good summary for the --manifest flag of the sf deploy metadata command is Full file path for manifest (package.xml) of components to deploy.
• For flags of type Boolean, which alter the behavior of a command but don't accept a value, the summary tells users what the flag makes the command do. Start these descriptions with an imperative verb.
  • For example, the summary for the global --json flag is Format output as json.
• Flag summaries use proper punctuation and capitalization and are complete sentences.

Description

• Flag descriptions are optional. They are displayed in the FLAG DESCRIPTIONS section of the --help output. They aren't displayed in the -h output.
• Write flag descriptions to expand on the summary, provide context and other helpful information for the user.
• Don’t duplicate information in flag descriptions that’s in your command description.
• Flag descriptions use proper punctuation and capitalization and are complete sentences.
• There’s no limit to the length of a flag description, but remember that short is sweet.

Examples

Examples are the best way to help a user understand what a command does.

• Examples are optional, but highly encouraged. They are displayed in the EXAMPLES section of the --help output. They aren't displayed in the -h output.
• For each example, provide a brief explanation. If it's helpful, also provide the context in which it runs, and the expected outcome. Don’t show the actual output, just a brief description of what it should be.
• If you provide multiple examples, note how they differ and when to use one over another.
• Don’t duplicate information in examples that’s already in your description values.
• If necessary, provide any prerequisites to help users run their own examples. Warn users of any “gotchas” they might encounter.
• To keep the examples operating-system agnostic, use <%= config.bin %> <%= command.id %> instead of sf your-command. The CLI converts this string to the appropriate OS prompt and command name at runtime.

Error Messages

Mistakes happen. But on the bright side, they’re opportunities to expand our users' knowledge of the CLI by providing them an excellent error message.

• Use an error message to tell users how to recover from the situation that caused the error.
• Before writing an error message, find out whether the design can be changed to avoid the error.
• Tell users concisely, but also completely, what went wrong and what they can do about it. For example:
  • Error message: This command doesn't accept an access token for a username.
  • Action (aka “Try this:”): Specify a username or an alias.
• Two short sentences are usually better than one long one. However, rather than first stating the problem and then the solution you can sometimes easily imply the problem in the solution. When possible, say what users can do instead of what they can’t.
• A good error message helps users move on rather than making them feel bad.
• Error messages use proper punctuation and capitalization and are complete sentences.