Output is providing information to a user.
Output can be categorized with number of input dimensions:
- 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.
- Human: Person using the application.
- Software: ReST API consumer.
- Both: Readable and parseable text output.
- 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|
|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|
|16||Pull||High||Software||Replace||Historical execution progress ReST API||Serialized|
|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.
- Success: Task has completed successfully.
- Break: Task has stopped for manual action not managed by the command.
- Error: Task has stopped with an error.
- Informatives: What the user needs to do next.
- 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.
- Use interactive elements to allow detail to be revealed when needed.
- Use consistent colour for different levels of detail.
- 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.