Document a shared team's desk signal meanings

Status Light can serve as a shared desk cue when a team agrees on the software state it represents. Without a written convention, the same colour can mean finished to one person and approved to another. Document the scope, evidence and expected action before making the signal part of everyday work. Keep the explanation near the integration and accessible to its users.

What belongs at the top of the legend?

Name the source and selected workload. State whether the display follows one task, a queue or an aggregate of several checks. Include a route to the detailed source record so the lamp points to evidence rather than becoming a substitute for it.

Describe each visible state in plain language with the lens position as well as the colour. Keep a text alternative available for people who cannot reliably read the physical signal. Do not assign meanings to output patterns that the actual hardware control has not been confirmed to support.

Which ambiguous states need explanation?

Cover completion, success, failure, idle and unavailable information to the extent the workflow uses them. If several internal states share one physical output, explain the broader meaning of that output and where to find the distinction. Do not let a simplified legend imply evidence the integration lacks.

Write down the freshness rule and recovery behaviour. A colour retained after disconnecting should not look like a newly verified result. Identify whether the companion status reports the last source check, last device write or both, because those timestamps answer different questions.

What should people do after noticing a signal?

Give each attention state a practical next step, such as inspect the selected failed run. Identify who normally handles it when the display is shared. A cue everyone notices but nobody owns can remain unresolved without any technical fault in the integration.

Separate acknowledgement from source actions. Clearing a local notification should not be described as approving, retrying or cancelling work unless it actually performs that distinct operation. Explain what happens when a new result arrives after acknowledgement so users know whether the light will notify again.

How should the document stay current?

Store the legend with the integration configuration and update both when state rules change. Keep a short record of material changes so a new interpretation does not surprise existing users. Test the written explanation with someone unfamiliar with the implementation.

Include a simple troubleshooting route for stale or contradictory signals and a way to stop relying on the lamp while investigating. The Status Light hardware overview describes the unit; shared trust comes from consistent rules, understandable documentation and a source of truth everyone knows how to inspect.