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.

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

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.