Stream: fhircast-github
Topic: fhircast-docs / Issue #181 May 2019 Ballot Comment:
Github Notifications (FHIRcast) (Apr 30 2019 at 19:53):
hl7-fhircast-bot opened Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Apr 30 2019 at 19:53):
hl7-fhircast-bot labeled Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Apr 30 2019 at 19:53):
hl7-fhircast-bot labeled Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Apr 30 2019 at 19:53):
hl7-fhircast-bot labeled Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Apr 30 2019 at 19:53):
hl7-fhircast-bot edited Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (May 06 2019 at 16:18):
isaacvetter commented on Issue #181
Tony,
This sounds like a critique of writing style. Do you have more specific suggestions on how to address this comment?
Isaac
Github Notifications (FHIRcast) (May 06 2019 at 19:46):
ajuliansr commented on Issue #181
i need to think about this one.
Github Notifications (FHIRcast) (May 07 2019 at 22:23):
isaacvetter commented on Issue #181
During conversation at the Montreal, May 2019 working group meeting, @wdbr, @wmaethner, @NiklasSvenzen and myself talked through this issue and would like to propose:
We will add a "abstract" section at the beginning of the specification page to make it more accessible, with liberal re-use from the Security Considerations page. Further, we will also re-use or create a flow diagram for this section. We believe this also addresses: #175
Proposed resolution: Persuasive
Github Notifications (FHIRcast) (May 08 2019 at 14:52):
NiklasSvenzen labeled Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (May 08 2019 at 18:10):
wmaethner labeled Issue #181
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Jun 05 2019 at 14:15):
wmaethner unlabeled Issue #181:
## May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Sep 05 2019 at 01:47):
isaacvetter commented on Issue #181:
Here's the overview section from when the spec was balloted:
The FHIRcast specification describes the APIs and interactions to synchronize healthcare applications in real time to show the same clinical content to a user. All data exchanged through the HTTP APIs MUST be sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818. FHIRcast is modeled on the webhook design pattern and specifically the W3C WebSub RFC and builds on the HL7 SMART on FHIR launch protocol.
An app subscribes to specific workflow events for a given session, the subscription is verified and the app is notified when those workflow events occur; for example, by the clinician opening a patient's chart. The subscring app may query a session's current context and initiate context changes by accessing APIs exposed by the Hub. The app deletes its subscription when it no longer wants to receive notifications. In all cases the app authenticates to the Hub with an OAuth 2.0 bearer token.
Overall, I've really struggled to implement this feedback of:
1) An overview section should not contain conformance language and should explain the specification, i.e. tell me what this thing is about. This comment is duplicated in #175, which suggests that the intro from the Security Considerations page is good. Here's the intro section from the Security Considerations page:FHIRcast enables the synchronization of healthcare applications user interfaces in real-time through the exchange of a workflow event to a small number of disparate applications. The notification message which describes the workflow event is a simple json wrapper around one or more FHIR resources. These FHIR resources can contain PHI.
It seems to me that the existing language in the overview section is actually better, more descriptive than the language in the Security Considerations page (which makes sense).
2) Whereas, issue #176, also from Tony, states that the overview section should be updated to correct the conformance language!
To address my understanding of the intent of the comments, I'm not creating an abstract section (because it would be duplicative of the existing overview section with a more obtuse title), rather, I'm enhancing it to contain language from the Security Considerations page, a flow diagram and separating language with conformance verbs into a separate paragraph in this section.
Isaac
Github Notifications (FHIRcast) (Sep 05 2019 at 01:52):
isaacvetter labeled Issue #181:
May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Github Notifications (FHIRcast) (Sep 05 2019 at 16:42):
ajuliansr commented on Issue #181:
I will need to think a while on this.
Anthony (Tony) Julian FHL7,MQF|IT Technical Specialist II|EIA Platform|Information Technology|Phone: 507-293-8384|Fax: upon request|E-mail: ajulian@mayo.edu<mailto:ajulian@mayo.edu>
Mayo Clinic | 200 First Street S.W. | Rochester, MN 55905 | www.mayoclinic.org<http://www.mayoclinic.org/>From: Isaac Vetter [mailto:notifications@github.com]
Sent: Wednesday, September 04, 2019 8:47 PM
To: HL7/fhircast-docs
Cc: Julian, Anthony J.; Comment
Subject: [EXTERNAL] Re: [HL7/fhircast-docs] May 2019 Ballot Comment: (#181)Here's the overview section from when the spec was balloted:
The FHIRcast specification describes the APIs and interactions to synchronize healthcare applications in real time to show the same clinical content to a user. All data exchanged through the HTTP APIs MUST be sent and received as JSON structures, and MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818. FHIRcast is modeled on the webhook design pattern and specifically the W3C WebSub RFC and builds on the HL7 SMART on FHIR launch protocol.
An app subscribes to specific workflow events for a given session, the subscription is verified and the app is notified when those workflow events occur; for example, by the clinician opening a patient's chart. The subscring app may query a session's current context and initiate context changes by accessing APIs exposed by the Hub. The app deletes its subscription when it no longer wants to receive notifications. In all cases the app authenticates to the Hub with an OAuth 2.0 bearer token.
Overall, I've really struggled to implement this feedback of:
1. An overview section should not contain conformance language and should explain the specification, i.e. tell me what this thing is about. This comment is duplicated in #175<https://github.com/HL7/fhircast-docs/issues/175>, which suggests that the intro from the Security Considerations page is good. Here's the intro section from the Security Considerations page:
FHIRcast enables the synchronization of healthcare applications user interfaces in real-time through the exchange of a workflow event to a small number of disparate applications. The notification message which describes the workflow event is a simple json wrapper around one or more FHIR resources. These FHIR resources can contain PHI.It seems to me that the existing language in the overview section is actually better, more descriptive than the language in the Security Considerations page (which makes sense).
1. Whereas, issue #176<https://github.com/HL7/fhircast-docs/issues/176>, also from Tony, states that the overview section should be updated to correct the conformance language!
To address my understanding of the intent of the comments, I'm not creating an abstract section (because it would be duplicative of the existing overview section with a more obtuse title), rather, I'm enhancing it to contain language from the Security Considerations page, a flow diagram and separating language with conformance verbs into a separate paragraph in this section.Isaac
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub<https://github.com/HL7/fhircast-docs/issues/181?email_source=notifications&email_token=ADSP6E56P5264RDRWW34JOTQIBQK5A5CNFSM4HJPVQRKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD55RMKQ#issuecomment-528160298>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ADSP6EZOU2ICKQSCYY3JK63QIBQK5ANCNFSM4HJPVQRA>.
Github Notifications (FHIRcast) (Sep 10 2019 at 13:55):
isaacvetter closed Issue #181:
May 2019 Ballot Comment:
Submitted by Anthony Julian
Chapter/section: Overview
Url: https://fhircast.hl7.org/specification/May2019Ballot/index.html
Type: NEG :exclamation: Clarification
In Person requested: Yes :bust_in_silhouette:Summary:
Comment: It is not typical to put conformance statements in an overview. The overview should tell me what this thing is about. Since this is a stand-alone document not included in FHIR, the overview should introduce the topic, as well as set the expectations for the rest of the document. In addition, it is necessary to either define the abbreviations such as app, or include a glossary.
_This issue was imported by @hl7-fhircast-bot from the consolidated FHIRcast May 2019 ballot spreadsheet._
Last updated: Apr 12 2022 at 19:14 UTC
