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

|#|Disclosure|Rate|Consumer|Accumulation|Example Scenario|Example solution| |:|:---------|:---|:-------|:-----------|:---------------|:---------------| |1|Push|High|Human|Append|Execution progress in CI / builds|Text| |2|Push|High|Human|Replace|Execution in interactive CLI|Progress bars| |3|Push|High|Software|Append|Execution progress delta web socket API|Serialized| |4|Push|High|Software|Replace|Execution progress web socket API|Serialized| |5|Push|High|Both|Append|none|| |6|Push|High|Both|Replace|none|| |7|Push|Low|Human|Append|Execution errors in CLI|Friendly errors| |8|Push|Low|Human|Replace|Execution outcome in CLI|Markdown output| |9|Push|Low|Software|Append|Execution errors web socket API|Serialized| |10|Push|Low|Software|Replace|Execution outcome web socket API|Serialized| |11|Push|Low|Both|Append|Execution errors in file|Friendly serialized| |12|Push|Low|Both|Replace|Execution outcome in file|Friendly serialized| |13|Pull|High|Human|Append|Historical execution progress logs|Text| |14|Pull|High|Human|Replace|none|| |15|Pull|High|Software|Append|none|Serialized| |16|Pull|High|Software|Replace|Historical execution progress ReST API|Serialized| |17|Pull|High|Both|Append|none|| |18|Pull|High|Both|Replace|none|| |19|Pull|Low|Human|Append|Execution errors in web page|Formatted errors| |20|Pull|Low|Human|Replace|Execution outcome in web page|Formatted report| |21|Pull|Low|Software|Append|Execution errors ReST API|Serialized| |22|Pull|Low|Software|Replace|Execution outcome ReST API|Serialized| |23|Pull|Low|Both|Append|Historical execution errors in file|Friendly serialized| |24|Pull|Low|Both|Replace|Historical execution outcome in file|Friendly 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.