Documenting the Profile Mechanism

Hi all,

We’d like to share our work on the the Profiles documentation for review and feedback. Please see:

  1. The updated Profiles, Variations, and Interoperability page which:
  • Provides a high-level description of the mechanism
  • Points people towards Profiles that we know about (i.e. the UK Profile)
  • Points people towards the Example Profile Repository as a starting point
    for building their own Profiles
  1. The expanded and updated README file on the Example Profile Repository which:
  • Now includes low-level details of how people can actually go about using it
  • Stepwise instructions
  • Lightweight worked examples for common things that a new Profile developer might find useful i.e. adding new properties, expanding the API specification etc

Both of these updates currently exist as branches on either the specification repo or the example profile repo ready to me merged once we’re happy with them.

Our goal was to create comprehensive, scope-appropriate docs relevant for whoever’s reading that particular time which hopefully we’ve achieved - but suggestions on how they can be improved are welcome.

FYI - We plan to reshuffle some pages/content emergent from this. However, we don’t think these tasks should hold-up the publication of profile documentation.

Also, FYI - Within this phase of work, we will be integrating some documentation tooling into the Example Profile repository to support people generating documentation for their profiles. This should cover the use cases of the “Minimal Profile” and support the generation of resources such as tables and diagrams for ORUK and future profiles.