Stream: smart
Topic: Resolving FHIR-32210
Josh Mandel (Aug 09 2021 at 21:10):
The last issue from SMART App Launch is FHIR-32210, which is asking to re-organize the spec according to IHE's conventions. I'm sure there are things we can do to improve clarity, but I'm also wary of committing to re-organizing the body of the spec without a very clear understanding of what it'd look like and what the advantages would be. Are there folks here who can speak in favor of these changes, or in favor of the status quo?
Josh Mandel (Aug 09 2021 at 21:10):
I'd love suggestions or feedback before next week's call, so we can work on this asynchronously and come to the FHIR-I meeting with a plan.
John Moehrke (Aug 09 2021 at 21:27):
I think the recommendation is that the pattern of documenting interoperability interactions be used. In IHE the technical specifications are always described as interactions, with each interaction described in terms of (a) trigger events, (b) message encoding, and (c) expected actions. These (a+b+c) patterns are repeated as much as possible. Where each interaction is described in UML interaction diagramming. Typically the (c) from one interaction causes the (a) of the next; but it is flexible to enable the first interaction to potentially cause multiple things, or have alternative interactions based on (c).
Josh Mandel (Aug 09 2021 at 21:32):
Thanks! Re-writing the whole spec to describe all interactions in UML diagramming (i.e., well beyond the sequence diagrams we use today) sounds like a daunting task!
Josh Mandel (Aug 09 2021 at 21:45):
(But I wonder if some subset of organizing principles would still be helpful?)
Eric Haas (Aug 10 2021 at 21:54):
I think the guide is dense , but it is readable. Perhaps add a home page with existing intro + "how to read this guide" section and section on actors?
Josh Mandel (Aug 16 2021 at 18:28):
Thanks for the background, feedback, and suggestions here! I've update the proposed resolution to improve clarity by adding an "Overview" page.
Carl Anderson (Aug 16 2021 at 20:02):
When I first started reading the guide, I was confused by the way that the sequence diagrams are supposed to be connected. For example, the IG lists steps 1-4 (but the first step is bifurcated into 2 sequence diagrams - one for EHR launch and one for standalone launch).
For reference, here are the four five high-level steps.
- App requests authorization
- EHR evaluates the request, prompting end-user input
- App exchanges auth code for a token
- App uses the token to access the FHIR API
- App uses a refresh token
This is nice and clear when presented this way, but these steps are sprinkled throughout the IG as section headers.
I think it would help readability if there were a top-level section that introduces these 5 major steps, possibly with a higher-level sequence diagram. I think this would help frame in the top-down readers mind what to expect from the sections that follow.
Josh Mandel (Aug 16 2021 at 20:03):
Would this go in the overview page, or still on the "Detail" page?
Carl Anderson (Aug 16 2021 at 20:07):
I could see it either way, but I was envisioning it as the first section in the Detail page.
Last updated: Apr 12 2022 at 19:14 UTC
