Write the dashboard copy for operators, not for reviewers - #10
Merged
Conversation
Three strings explained why the code is built the way it is, which is a code comment's job rather than a UI's. Spotted in the tab, not in review. * the hidden-connections note argued its own design — "a Pause button next to them is a misclick away from an outage". An operator needs to know the connections exist and why they are absent, not to be sold the reasoning. * the empty state told you to set `HOOKDECK_API_KEY`. That still works as a fallback, but the name to reach for since the namespacing is `HOOKDECK_EG_API_KEY`, so the tab was teaching the older one. * the agent-runs caption said "failed after the 202". Nobody reading a dashboard is thinking in status codes. The pause guidance and the stranded-runs warning are unchanged: both state a symptom and an action, which is the line. Ships in the wheel, so this wants a patch release. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Caught while setting up a screenshot for the announcement post — the Connections card was telling the reader that "a Pause button next to them is a misclick away from an outage." That is a design rationale. It belongs in a code comment, which is where the same sentence already lives.
Three strings had the same problem:
N other connection(s) … are not shown — they belong to something else, and a Pause button next to them is a misclick away from an outage.N other connection(s) in this project are not shown. Only connections matching a configured route appear here.HOOKDECK_API_KEY is not set, so the queue cannot be read. The adapter still runs — this tab is read-only observability, not a dependency.Set HOOKDECK_EG_API_KEY to show queue and delivery data here. The gateway keeps running without it.From the local ledger. A run that failed after the 202 is only visible here — …What this gateway did with each delivery. A run that failed after the event was accepted appears only here — …The middle one was also wrong, not just wordy: it named
HOOKDECK_API_KEY. That still works as a fallback, but since the namespacing the name to reach for isHOOKDECK_EG_API_KEY— so the empty state was teaching the older variable to exactly the person who does not have one set yet.The pause guidance and the stranded-runs warning are unchanged. Both state a symptom and an action, which is the line between useful and self-justifying.
Verified in a running dashboard rather than by reading the diff.
hookdeck/dashboard/is inside the wheel, so this is a patch release when you want it — no rush, v0.1.2 is fine to leave standing.