Upgrade to UK standard and compliance rules (version 3.0)

Technical
,
4

Well done OR UK! This looks great! I had a few thoughts about the Profile docs:

  • I think that the framing of “Open Referral UK Profile 3.0.0” might be a little bit confusing. Currently, HSDS is version 3.0 and previous OR UK Data Standard states itself to be version 1.0. I think there’s arguments to say that the new OR UK Profile is either version 1.0 of a new thing, and replaces the old OR UK standard, or is version 2.0 of that standard which just happens to have been implemented as a Profile of HSDS 3.0. There is likely a larger conversation to have around how Profiles should version themselves, which is out of scope for this thread! For now, if you’re in agreement then I think the “fix” is just a statement on your docs landing page explaining how you arrived at your version number (whichever number you end up choosing!).
  • I’m sure you’re aware but as an FYI there’s some boilerplate text from the Example Profile, at the top of each docs page which should be adjusted or removed. This is particularly prevalent on the API Reference Page
  • Since the API Reference Page and the SwaggerUI link on the sidebar repeat the same content you could probably remove the API Reference Page entirely. The core HSDS docs link to the SwaggerUI from the canonical API Reference page as a special treat for developers familiar with SwaggerUI, but our discussions indicated to me that fore-fronting the SwaggerUI page was a priority for the UK Profile. Therefore it might be best to avoid confusion and treat the SwaggerUI as the canonical API Reference for your Profile and remove template API Reference page.
  • The Changelog page boilerplate states that it’s intended to be used for internal versioning changes to the Profile. I think when I set up the proof-of-concept docs for the Profile, I probably put these in the wrong place so I’ll own this one! I think there’s two jobs for the docs wrt “changes”: (1) Inform people what changes the Profile makes against the base HSDS 3.0 model/schemas (2) inform people of internal version changes (i.e. if the OR UK Profile goes from version 1.0 to 1.1 etc). I think “Changelog” is usually used for the latter, so to prevent confusion I think the current content of Changelog should probably be migrated to e.g. Profile Compliance, and then the Changelog page can contain the changes from version 1.0 of the UK Profile to the current version.

This is really good to see that you’ve been able to spin this up so quickly and effectively.