Understandability

Presentation / verbosity.

Show information when it's relevant, hide information when it's not.

Maturity Levels

📃 Text, text everywhere..

Show the user 200 MB of uncoloured logs per minute.

2021-02-21T15:13:01.123 | Debug | my::krate::module | Starting application.
2021-02-21T15:13:01.325 | Info | another::krate::module | Connecting to server.
2021-02-21T15:13:01.500 | Debug | third::krate::module | Resolving DNS for `some.domain.com`.
2021-02-21T15:13:01.531 | Debug | someones::krate::module | Looking up name server for `some.domain.com`
2021-02-21T15:13:01.570 | Debug | third::krate::module | DNS Resolved to 1.2.3.4
..
🎨 Beautiful

"The ultimate complexity is simplicity."

  • Show useful information.
  • Hide unnecessary information.
  • Could: Show progress detail for current step, hide detail when it's done.
  • Highlight important information, dim contextual information.

Example progress:

❯ ./target/release/examples/demo --concurrent
✅ a Upload App         [████████████████████████████████████████] 26.01KiB/26.01KiB (0s Ok!)
⠦⠦b Create DB          [███████████████████████████░░░░░░░░░░░░░] 68B/100B (0s 1s)
✅ c Download App       [████████████████████████████████████████] 26.01KiB/26.01KiB (0s Ok!)
⏳ d Link App to DB     [                                        ] 0/100 (queued)
⏳ e Run App            [                                        ] 0/100 (queued)
⠤⠤f Allocate Domain    [██████████████████████████░░░░░░░░░░░░░░] 67B/100B (0s 1s)
⏳ g Attach Domain      [                                        ] 0/100 (queued)
⏳ h Notify Completion  [                                        ] 0/100 (queued)

Example error:

❯ ./target/release/examples/demo --concurrent
❌ a Upload App         [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0B/772.42KiB (0s)
☠️ b Create DB          [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
☠️ c Download App       [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
☠️ d Link App to DB     [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
☠️ e Run App            [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
✅ f Allocate Domain    [████████████████████████████████████████] 100B/100B (0s Unchanged)
☠️ g Attach Domain      [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
☠️ h Notify Completion  [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/100 (parent failed)
error[E06]: Failed to connect to artifact server.
  ┌─ artifact_server_address:1:8
  │
1 │ http://127.0.0.1:8000
  │        ^^^^^^^^^^^^^^ failed to connect to server
  │
  = Try running `simple-http-server --nocache -u --ip 127.0.0.1 --port 8000`.

API Implications

  • Provide mechanism to specify end limit and progress.

  • Collect information, present it in a useful way:

    • Real time interactive CLI presentation.
    • Useful errors.

choochoo currently uses indicatif to display progress, and codespan-reporting to display errors.

indicatif provides:

  • Progress rendering
  • Elapsed time
  • Estimated time remaining
  • Styling