Uploaded image for project: 'FHIR Specification Feedback'
  1. FHIR Specification Feedback
  2. FHIR-35755

Change Home Page to an explanation to exec summary of the problem and solution

    XMLWordPrintableJSON

Details

    • Change Request
    • Status: Published (View Workflow)
    • Highest
    • Resolution: Persuasive with Modification
    • US Core (FHIR)
    • 4.0.0
    • Cross-Group Projects
    • STU
    • Home
    • 1
    • Hide

      Background:

      The Note to Balloters is published in the Continuous Integration (CI) Build and Ballot Version to describe the changes for the current ballot cycle (pre and post ballot). It is not part of the specification and is not in the final published version. It is migrated to the change log in the publication history upon publication.

      This IG is unique because it describes a foundational set of profiles and associated FHIR Search API.  As such it does not have a single use case or focus on a particular set of interactions. Instead this IG provide general guidance over several use cases to which the reader is directed to under the section "How to read this guide".

      Reasoning:

       
      The main purpose of balloting US Core is to get public comment on the new and updated content. Thus, a list of changes on the home page will assist the balloters in reviewing this new and updated content. Since it is migrated to the history page when the guide is published, it won't detract from the content.

      US Core is a technical specification to enable a wide variety of use cases. We would consider adding a few very generic scenarios, or reference other guides, if the commenter chooses to submit. There are a handful of pages devoted to individual use cases.

      We agree with the commenter that a basic introduction to the FHIR RESTful Search interaction in the home page may help orient the novice reader to the US Core API.

      Proposed Changes:

      1. In the future ballot publications will point out that The Note to Balloters:
        1. is not part of the specification and will not be in the final published version.
        2. describes the changes for the current ballot
        3. will be migrated to the change log in the publication history
        4. Direct readers to the published specification if they are not participating in the ballot.
      1. Will add a basic introduction to the FHIR RESTful Search interaction in the home page:
        1. include a sequence diagram
        2. reference the FHIR Search page.

      Suggestion:

      Feel free to submit Jira issues for specific recommendation for a particular artifact or use case that is considered too technical.

      Show
      Background: The Note to Balloters is published in the Continuous Integration (CI) Build and Ballot Version to describe the changes for the current ballot cycle (pre and post ballot). It is not part of the specification and is not in the final published version. It is migrated to the change log in the publication history upon publication. This IG is unique because it describes a foundational set of profiles and associated FHIR Search API.  As such it does not have a single use case or focus on a particular set of interactions. Instead this IG provide general guidance over several use cases to which the reader is directed to under the section "How to read this guide". Reasoning:   The main purpose of balloting US Core is to get public comment on the new and updated content. Thus, a list of changes on the home page will assist the balloters in reviewing this new and updated content. Since it is migrated to the history page when the guide is published, it won't detract from the content. US Core is a technical specification to enable a wide variety of use cases. We would consider adding a few very generic scenarios, or reference other guides, if the commenter chooses to submit. There are a handful of pages devoted to individual use cases. We agree with the commenter that a basic introduction to the FHIR RESTful Search interaction in the home page may help orient the novice reader to the US Core API. Proposed Changes: In the future ballot publications will point out that The Note to Balloters : is not part of the specification and will not be in the final published version. describes the changes for the current ballot will be migrated to the change log in the publication history Direct readers to the published specification if they are not participating in the ballot. Will add a basic introduction to the FHIR RESTful Search interaction in the home page: include a sequence diagram reference the FHIR Search page. Suggestion: Feel free to submit Jira issues for specific recommendation for a particular artifact or use case that is considered too technical.
    • Brett Marquard/Eric Haas: 15-0-0
    • Correction
    • Non-substantive

    Description

      The Home Page is  technical note to balloters.  That is the first impression anyone will have if they google for this spec. This is the first page everyone will read.  It should be an advertisement for the project to executives, non-technical people, and technical people alike. It should include actual stories/scenarios that explain the overall purpose of the spec.   Having that high level overview that explains the important problem this guide solves with relatable scenarios will draw people in.  If someone looks at a document they expect it to start with a glossy executive summary that motivates them to read the rest of the document and if they do not have time to do that, motivates them to tell someone else to do it.  This spec is helping to solve a really important problem and that is lost in the details.    I realize that this seems to be a common shortcoming in the FHIR IGs but I think it is wrong.  Also, recommend a high level sequence diagram that goes allow with a general scenario or with use cases either here or under use cases section.  US Core is way too technical in general.  The Note to Balloters should instead be its own Tab or after the summary.

      Attachments

        Issue Links

          Activity

            People

              Unassigned Unassigned
              vlorenzi Virginia Lorenzi
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: