First off, some official business about HSDS:
Proposed upgrade to Human Service Data Specifications: version 3.2
Our Technical Committee has approved a set of proposed changes that our Technical Steward has bundled into a proposed minor upgrade – as announced in our forum, previewed in our documentation site, and managed in Github.
This upgrade presents improvements to the format of our API specifications – specifically including extensions of metadata:
- tagging API endpoints to correspond with HSDS specs,
- adding provenance metadata about data publishers and technology providers,
- adding a field for a link to a data guide through which implementers can provide specific documentation about their dataset and API feed. (See more about the proposed ‘data guide’ framework in this forum post.)
This upgrade is now open to comments from the community for the next two weeks; if we identify no significant issues during that time, HSDS will then be automatically approved.
Feel free to ask questions or express concerns in the Github repo or Forum via the links above – or reach out to discuss directly!
Now, while I have your attention:
We’ve made a bunch of upgrades to our documentation over the past year, and I’m excited to share a set of updates about these improvements here:
Open Referral’s FAQs: updated and reorganized
Across over ten years of operation as a community, the number of Frequently Asked Questions about Open Referral gradually proliferated to the point where we ended up with multiple redundant FAQ silos. How ironic!
Through significant effort we have now standardized and rendered interoperable these Frequently Asked Questions into a single set that is published in different subsets across both our main community webpage and documentation site.*
Do you have a question that isn’t asked in there? Or do you want a question in there to be answered more thoroughly? Reach out directly, or chime in on our Forum: here’s a relevant thread.
Product documentation: upgraded on Docs.Openreferral.org
We have made various improvements to the documentation of the Human Service Data Specifications, which you can browse here (and discuss in the Github issue queue or our forum).
These improvements include:
- Integrated our API protocol documentation into the main HSDS Reference section
- Updated our Entity-Relationship Diagrams
- Organized a consolidated section of “HSDS Implementation Guidance”*
- Deprecated previous versions of HSDS.
Is there something you would like to see improved in our documentation? How-to material that you need, or perhaps have developed and would like to share? Reach out to discuss further.
Core project documentation: staged on Openreferral.org
Core documentation of the Open Referral initiative – including our basic governance model – has been moved to the website’s About section.
We have also created an About Us page, which includes names, bios, and faces of all the people that drive Open Referral forward – including our core leadership, technical stewardship, fiscal sponsor, and technical committee members. Check us out!
Operational project documentation: shared in a public folder
We have re-organized over a decade worth of project documents – thousands of google docs and spreadsheets! – into a consolidated and streamlined shared folder.
You can see here for an index of all of our documents.
In particular, I’m excited to share the new folder for Templates. Many processes and frameworks applied in this community are replicable and generalizable, so we’ve templatized some common artifacts which you can now copy to adapt for your own use. It’s all free – we just ask that you preserve the open license and attribution to Open Referral. And we hope that if you use these materials, you’ll let us know about it!
Join us in the Open Referral Forum.
Please note that we have recently sunsetted our Slack team.***
Now we encourage all discussions among our community members to take place in the Discourse forum here. Please join!
* To wrangle our FAQs into an integrated set of content distributed across multiple locations, we did use some tooling – but this was mostly just a matter of establishing dedicated labor for maintenance and clear protocols for what goes where and how. Relevant lesson!
** The guidance materials in our documentation are described as ‘non-normative,’ which I as an English major find very confusing, because the term literally implies something that one ought not do, but by this our developers actually mean these materials are helpful but not considered formally part of the standard. In other words, this guidance documentation is here to provide tutorials and how-to assistance – stuff you probably ought to do when implementing, but none of it is strictly required.
*** Bye Slack! 2014 was a fun time, but you are not missed 🙂
Leave a Reply