Documenting the Profile Mechanism

Technical
1

Hi all,

We’ve started work on supporting documentation for the profiles mechanism & example created by @davidraznick

To support us in this work, could we please request that you post any profile-related questions you may have in response to this post? Or, if you do not want to do that publicly, you can email me direct at dan.smith@opendataservices.coop

We will use your questions to inform the content of the documentation.

Many thanks in advance,

Dan

2

Thanks @Dan-ODS . I’m part of a work group that is assembling best practices for 211s for certain data fields. I could see that becoming a profile, but we aren’t ready to implement it to that degree yet.

1 Like
3

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.

Thanks,

Dan

4

Hi all,

Just to let you know, the updated Profiles, Variations and Interoperability page has now been merged into the main docs.

This links to the Example Profile Repository which we have updated further since our request for review and feedback.

The README.md now includes a Preparing Documentation section where guidance on use of the profile documentation tools we’ve provided can be found.

We would still welcome feedback and will, of course, be looking iterate on this documentation as we gain further insights based on their use.

Thanks @mrshll for the great work!

Dan

1 Like