Making Automation Output Operator-Friendly
Output Is an Interface¶
Operators trust tools that communicate clearly under stress.
Poor output creates avoidable delay:
- Raw command dumps with no interpretation
- Long stack traces without action hints
- Success messages that hide partial failures
Good output supports fast, correct decisions.
Output Design Principles¶
Every run should answer:
- What changed?
- What failed?
- What was skipped and why?
- What should the operator do next?
Make these answers visible at summary level first, then allow detail drill-down.
Recommended Output Layers¶
- Layer 1: Executive summary (counts, status, duration)
- Layer 2: Per-device outcomes with reason codes
- Layer 3: Technical details (diffs, command output, trace IDs)
This keeps high signal visible without hiding depth.
Error Message Standard¶
Useful structure for errors:
- Error code: stable identifier
- Context: device, phase, operation
- Impact: what was blocked or degraded
- Next action: specific operator guidance
Example:
PRECHECK_AUTHZ_DENIED: device=lon-core-01 phase=validation impact=write_blocked action=verify AAA role and rerun pre-flight.
Production Checklist¶
- Summary section appears at the top of every run
- Failures include stable reason codes
- Partial success is explicitly represented
- Logs include correlation IDs for each run
- Operator next actions are included for all critical failures
Anti-Patterns¶
- Treating logs as only developer diagnostics
- Unbounded raw output in primary console view
- Inconsistent error naming between workflows
- Green success banner despite blocked targets