Hi folks,
I’d like to present the start of some work to the to the community around producing some guidance for HSDS publishers to write Data Guides for their API feeds where appropriate. The document linked below contains our initial idea of what a publisher’s HSDS Data Guide should contain (i.e. what questions it should answer), but we’re very keen to have this based on community needs and therefore we’d really like your input. Please add your comments and suggestions to the doc!
- Outline of ideas for HSDS Data Guide template (there are multiple tabs in this document, you want the one titled Outline of needed information)
We’ve also spun up a (very) draft proposal in another tab. This proposal handles the technical side of what it would take to link to such a document from an API feed. We will formalise the proposal if the community think that Data Guides are a good idea and once we have a better idea of the guidance needed to support people.
For the uninitiated, Data Guides are human-readable documents (web pages, pdfs etc) which are designed to support humans such as developers or analysts understanding the data and they’re designed to fill in the gaps where the machine-readable metadata cannot describe the nuances of the data appropriately. This would be things such as listing those involved in producing the data feed in various roles (thanks to @skyleryoung for illuminating this), and describing any limitations on the data’s scope or coverage of fields etc.
This arose from the discussion on the other forum thread around Extra Metadata with API feeds.
- Forum thread: Extra Metadata with API Feeds