Profiles documentation #446
Conversation
… separated out in-depth technical guidance to the Example Profile readme
minor copy-editing
Update variations_interoperability.md
There was a problem hiding this comment.
Wonder if a bullet-point list of things a profiles allows you do could be useful?
Profiles may declare new optional or mandatory fields, make existing optional fields mandatory, introduce new validation rules or new structures, or declare new API endpoints in addition to those on the HSDS API Reference.
Conversely, Profiles may also remove or override some parts of the HSDS Schema which are not relevant to them. (This will not prevent a publisher from publishing such excluded data, but it may not be validated by tooling used by that Profile, as it is technically additional data from the Profile's perspective.)
There was a problem hiding this comment.
I've restructured as a bullet point list. It might need a bit of word-smithing, but I agree seeing a bulleted list of what a profile can do is generally more readable/accessible than having this information in a series of paragraphs.
There was a problem hiding this comment.
Speaking to people who have implemented other HSDS Profiles may help you with thinking through some aspects of Profiles.
Not sure about the end of this sentence.
@dan-odsc - Reminder to self to propose re-worded version.
There was a problem hiding this comment.
I've refactored to read:
Speaking to people who have implemented other HSDS Profiles may help you with thinking through common challenges when developing a new Profile.
This PR changes the existing Variations and Interoperability Page to "Profiles, Variations, and Interoperability" as a first step in both documenting the Profiles mechanism and reorganising some documentation.
@greggish has already reviewed, with some copy-edits having been integrated via #445, and I've responded to some sentence structure errors kindly highlighted by a member of the community as well.
I'm intending to flag this PR in a forum post to the community, and then ideally we can get this merged to go live sometime next week.
Have tagged some potential reviewers but depending on availability we likely can go ahead with the merge unless a community member flags something concerning.