What Should a Download Page Explain About Freshness?
From the earlier reference collection. Read the current software blog.
Separate the identity of a dataset from the times it was published, retrieved, and last successfully refreshed.
Identify the dataset version
A download page should tell readers which dataset they are getting. Show a version identifier when the source provides one, or a stable publication label generated by the project. Explain what the identifier represents: a source release, a file revision, or the time your service assembled a snapshot. These are different things, and a timestamp should not be made to stand in for version identity unless that is genuinely how the data is versioned.
For example, “feed version 42” might describe the upstream provider's release, while “snapshot built 2026-10-28 14:00 UTC” describes your own export. Label both if both are useful. If there is no formal version, say that the download is an unversioned current snapshot and include a checksum or filename that can help readers distinguish copies.
Show publication and retrieval times
Publication time answers when the source says it issued the data. Retrieval time answers when your service last fetched it successfully. Display both with an explicit time zone. A page that says “Updated at 9:00” leaves the reader to guess which clock was used and what event “updated” refers to.
A practical status block might read: “Source publication: 2026-10-28 13:40 UTC. Last successful retrieval: 2026-10-28 13:52 UTC. Export generated: 2026-10-28 13:54 UTC.” The values are only an example of the labels; populate them from recorded events. If the source does not expose a publication time, state that it is unavailable rather than substituting your retrieval time.
Explain gaps and stale copies
Freshness is a relationship between these times and the expected update pattern. Explain how often the source is expected to publish if that schedule is known, and what happens when a retrieval fails. If the last successful retrieval was yesterday while attempts continue to fail, keep the success time visible and show the current failure state separately. Do not advance the success timestamp merely because a scheduled job ran.
For example, a page might say that its file remains available but represents the last successful fetch, which occurred at 08:15 UTC, and that later attempts have not completed. This is more informative than a generic “live” badge. State whether cached data can remain downloadable and whether a partial response is ever published.
Make the download traceable
Tie the displayed information to the specific file. A reader should be able to tell whether the metadata refers to the link they clicked, a page-wide feed, or a newer file that appeared afterward. Include a manifest or metadata file when multiple outputs are distributed together, and document the fields in it. Keep timestamps in a consistent machine-readable format in downloadable metadata, even if the page renders them more readably.
A good freshness explanation lets a user make a decision: use the file, wait for another retrieval, or investigate a mismatch with the source. State the limits of the timestamps, including clock synchronization or missing upstream metadata if relevant. Clear labels make a quiet refresh failure visible without implying that every download is current.