How Can Documentation Avoid Unsupported Reliability Claims?
From the earlier reference collection. Read the current software blog.
Describe what was measured, where the measurement stops, and what readers should infer from it.
Replace promises with observed behavior
Reliability language becomes misleading when it promises more than the system has measured. Words such as “always,” “accurate,” and “real time” suggest broad guarantees. Documentation should instead describe a specific observation: which component was checked, during what interval, and what result was recorded. If the project has no monitoring history, explain how the service behaves by design without implying that it has operated continuously.
For example, “The page refreshes after a successful source retrieval” describes a mechanism. “The page is always current” makes a claim about every retrieval and every moment, which requires evidence the mechanism alone does not provide. State which layer is covered: the public page, the data collector, an upstream source, or the user's network.
Define the measurement
When reporting availability or freshness, identify the measurement window, denominator, and failure rule. If a monitor checks every five minutes, a missing check might mean the monitor failed, the site failed, or connectivity was interrupted. Explain how such gaps are handled. A percentage without a method can conceal these distinctions.
Suppose a dashboard records 98 successful checks out of 100 scheduled checks. That is a count for that sample, not proof that every user could access the service throughout the interval. Say where checks ran, what endpoint they requested, whether they tested a full data refresh, and how long the observation lasted. If those details are unknown, publish the raw status history or limit the claim to the narrower fact that was observed.
Explain accuracy limits and uncertainty
A displayed value may faithfully reflect an input while the input itself is delayed, estimated, or later corrected. Distinguish data transfer integrity from the real-world accuracy of a measurement. For a sensor reading, documentation could say that the interface displays the source's reported value and timestamp, while the project has not independently calibrated the sensor. That is more useful than describing the number as simply accurate.
Likewise, a map marker may be positioned from a published coordinate whose precision is limited. If a value is transformed or rounded, describe that processing and its likely effect. Do not attach a precision claim merely because the output has many decimal places.
Give readers a usable status
A careful reliability note can still help people decide what to do. Show the last successful update, the last attempt, and a clear state such as “current,” “delayed,” or “unavailable,” with definitions for those labels. State the threshold that changes a state where one exists, and avoid describing a temporary state as a system-wide outage without evidence.
Close by explaining the consequence: a delayed display may still be useful for historical context, but it should not be treated as a current observation. A reader who knows the measurement and its limits can judge whether it suits the task. Update the note when monitoring coverage changes, and preserve the method alongside any reported result.