What Belongs in a Public Data Source Note?
From the earlier reference collection. Read the current software blog.
A useful source note tells readers who publishes the data, how it is retrieved, when it changes, what terms apply, and where interpretation has limits.
Identify the publisher and the path
Name the organization that publishes the data, using the name readers will find on its site or files. If a government office, research group, or service provider supplies it, distinguish that publisher from your own project, which may copy, transform, or display the material. Add a direct link to the source page or dataset rather than a generic home page when possible.
Describe how your project obtains the data in ordinary terms: for example, downloading a published file each morning or requesting a public endpoint when a user opens a page. Include the retrieval date or the date the note was last checked. If a process changes the source data, briefly name the transformation, such as converting timestamps to a common zone or dropping records without coordinates.
Make freshness and terms visible
State the provider’s announced update cadence separately from your own retrieval cadence. A dataset described as daily may arrive late, and a tool that checks hourly does not make the underlying measurements hourly. A concrete note might say: “The provider publishes a new file each weekday; this project checks for it at 06:00 local time and retains the last successful copy.” Avoid promising a refresh schedule you cannot observe or control.
Name the applicable license or terms and link to the full text. If code and data have different terms, say so explicitly. Do not infer that material is free to reuse merely because it can be downloaded publicly. When the provider’s terms are unclear, say that the project has not established reuse permission instead of assigning a license on its behalf.
Explain the boundaries
List limitations that could change how someone reads the data: coverage gaps, delayed reports, estimated values, known unit conversions, or fields your tool does not preserve. Make each limitation concrete. “Some locations do not report every day” is more useful when paired with the affected location or date range, if known. Distinguish confirmed gaps from possibilities you have not checked.
A compact note should let a reader answer five questions: who supplied this, how did it reach this project, how current might it be, what terms govern reuse, and what should I be careful not to conclude? For instance, a dashboard showing yesterday’s reading should identify the source timestamp and retrieval time, so a stale feed is not mistaken for a current observation. Review the note when the provider, process, terms, or known coverage changes.