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.
Example scenarios and solutions for different output combinations
#DisclosureRateConsumerAccumulationExample ScenarioExample solution
1PushHighHumanAppendExecution progress in CI / buildsText
2PushHighHumanReplaceExecution in interactive CLIProgress bars
3PushHighSoftwareAppendExecution progress delta web socket APISerialized
4PushHighSoftwareReplaceExecution progress web socket APISerialized
7PushLowHumanAppendExecution errors in CLIFriendly errors
8PushLowHumanReplaceExecution outcome in CLIMarkdown output
9PushLowSoftwareAppendExecution errors web socket APISerialized
10PushLowSoftwareReplaceExecution outcome web socket APISerialized
11PushLowBothAppendExecution errors in fileFriendly serialized
12PushLowBothReplaceExecution outcome in fileFriendly serialized
13PullHighHumanAppendHistorical execution progress logsText
16PullHighSoftwareReplaceHistorical execution progress ReST APISerialized
19PullLowHumanAppendExecution errors in web pageFormatted errors
20PullLowHumanReplaceExecution outcome in web pageFormatted report
21PullLowSoftwareAppendExecution errors ReST APISerialized
22PullLowSoftwareReplaceExecution outcome ReST APISerialized
23PullLowBothAppendHistorical execution errors in fileFriendly serialized
24PullLowBothReplaceHistorical execution outcome in fileFriendly serialized

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 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


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.