Output

Output is providing information to a user.

Output can be categorized with number of input dimensions:

• Disclosure:
  • Push: Information is pushed to users once available.
  • Pull: Information is requested by users, may be real time or historical.
• Rate: (of requests)
  • High: Information that constantly updates.
  • Low: Information that once created isn't expected to change.
• Consumer:
  • Human: Person using the application.
  • Software: ReST API consumer.
  • Both: Readable and parseable text output.
• Accumulation:
  • Append: Information continuously increases.
  • Replace: Latest information is relevant.

From the above table, further thoughts include:

• Information that changes at a high rate implies a high rate of requests.
• Information requested at a high rate may need to be small (in size).
• Progress output is frequent, and is most important in real time / as it happens.
• If frequency is high and the output is transferred between hosts, then ideally the size of the output is reduced.
• The point of serialized data without the friendliness requirement is space and time efficiency.
• Friendly serialized data may be a format such as YAML / JSON / TOML.
• Pulled data is either over an API, or viewing historical information, meaning pulled data needs to be serializable.
• Web page output may be large, but mental overload can be avoided by hiding information through interactivity.

Outcome

Outcome Status

• Success: Task has completed successfully.
• Break: Task has stopped for manual action not managed by the command.
• Error: Task has stopped with an error.

Outcome Messages

• Nothing
• Informatives: What the user needs to do next.
• Warnings

Outcome Errors

• What happened
• Why it is considered an error
• Source of the information that led to the error
• Suggestions for fixing

Format

Output format can be optimized for different consumers. For example:

• Interactive command line:

  • Hide detail to reduce mental overload.
  • Show enough to give an appropriate picture.
  • Use colour to highlight / dim detail based on level of importance.
  • Show commands to display additional detail.
  • Use a format that makes sense when copying and pasting into a different application, e.g. markdown.

• Web page:

  • Use interactive elements to allow detail to be revealed when needed.
  • Use consistent colour for different levels of detail.

• Network transfer:

  • Use a serialization format that is small to cater for latency.
  • Use a serialization format that is not difficult to deserialize to reduce CPU utilization.