Stream: ig publishing requirements
Topic: hello
Welcome Bot (Apr 17 2019 at 21:35):
Welcome to #ig publishing requirements.
Description: For discussion of page http://wiki.hl7.org/index.php?title=FHIR_Implementation_Guide_Publishing_Requirements
Grahame Grieve (Apr 17 2019 at 21:35):
so creating this after vigorous dicussion on FMG about this subject
Grahame Grieve (Apr 17 2019 at 21:37):
outcomes:
- we will create a Zulip stream for this specific discussion (and here we are)
- FMG happy to consider and approve an example IG once it exists
- vigorous discussion about what the basic requirements are. TO be discussed for a week in this thread
Grahame Grieve (Apr 17 2019 at 21:38):
no issues around the technical publication requirements - they stand (header, footer, npm stuff), and html requirements
Grahame Grieve (Apr 17 2019 at 21:39):
Most discussion was around how for to go in terms of requirements for
- presentation of particular resource types
- presentation of indexes / navigation
- common look and feel
Grahame Grieve (Apr 17 2019 at 21:39):
in particular, some of this section will be turned into SHALL and fleshed out:
Profiles should at least have the following elements presented:
** full metadata
** differential view
** snapshot view
** full description of contents with details
Value Sets should have the following elements presented:
** full metadata
** logical definition
** at least one expansion (default)
Grahame Grieve (Apr 17 2019 at 21:41):
a page like this one (http://hl7.org/fhir/us/bser/2019May/BSeRArthritisFeedbackObservation-duplicate-2.html) is a problem
Lloyd McKenzie (Apr 17 2019 at 22:56):
I think it's optimistic to believe we'll have landed the discussion on what should be in an IG in only a week. It's going to take several weeks minimum to figure out what the hl7 template should look like and possibly more time to agree on what subset of that is mandatory for ballots published without the template.
Rien Wertheim (Apr 18 2019 at 07:21):
a page like this one (http://hl7.org/fhir/us/bser/2019May/BSeRArthritisFeedbackObservation-duplicate-2.html) is a problem
Why is this page a problem?
Grahame Grieve (Apr 18 2019 at 07:56):
so here's my comments about that page:
- it does not state the URL of the profile, or it's version, or other key metadata
- it does not identify whether it is showing a differential or a snapshot - both are needed
- there is no presentation of field level documentation
- the UML view is not useful (though not objectionable)
- it's not a printable view
- the element binding information is not linked to anything
- the table view doesn't add anything
- there's no link to examples (I don't know if that is infrastructure or editors fault)
- there's no links to other formats
- there's no mapping information (again, might be the editor)
Grahame Grieve (Apr 18 2019 at 07:57):
Lloyd wishes for the tree view to be highly aligned so that balloters only need to deal with one presentation. I think that's pretty a reasonable requirement
Michel Rutten (Apr 18 2019 at 08:32):
For this particular IG, the editor was struggling and pressed for time, so that might explain some of the omissions or lack of detail.
Rien Wertheim (Apr 18 2019 at 08:32):
Okay thanks Grahame. We will look into this.
Grahame Grieve (Apr 18 2019 at 09:56):
yes. if I was commenting to the editor I would have given a different long list of issues. that profile is very poor quality work, and would not pass the IG publisher quality criteria, but because it came from elsewhere, I didn't apply all the quality criteria. FMG are not happy about that
John Moehrke (Apr 18 2019 at 13:54):
I think we can define some of these 'functionally', but am very worried if we start to define them too tightly. That is to say it is clear we could today require a 'differential view', and that 'differential view' can be described in terms of what it is showing and not showing. I think that it is too early in our maturity at what a IG layout should be for us to be too specific on the human readable format. For example it is fragile if we call for specific color of the lines in the differential view, or even that there are lines between elements ; or even that the rendering must be done with a specific tool. What I am worried about is that we are too new to this IG layout, and that we will find that creativity is needed to come up with specifics we can then universally apply. There are far too few people defining this 'perfect layout', and there is a huge audience of readers. Many of our readers have never been exposed to standards, especially HL7 or FHIR.
Lloyd McKenzie (Apr 18 2019 at 15:51):
I'm happy for creativity in the design of IGs, I'm less comfortable with diversity in the presentation of IGs. I'm happy to have people experiment with alternate templates and when they have something they think is useful to share it and allow the HL7 community to adopt it as part of the standard template. (And of course other organizations can experiment to their heart's content.) But I also think that it's important that an implementer looking at three different (but potentially related) HL7 balloted IGs should find that they work mostly the same way. There should not be a learning curve to understand how to interpret profiles or how to navigate when moving from one HL7 published IG to another. That doesn't necessarily mean they must be absolutely identical, but they should be pretty close and the differences should require minimal incremental learning.
Martijn Harthoorn (Apr 19 2019 at 09:59):
Can we rename this specification to "HL7 Ballotable FHIR Implementation Guide publishing requirements" or something like it. Calling this "FHIR IG publishing requirements" suggests that an IG that does not meet these requirements does not meet the FHIR standards requirements, which is not the case.
Grahame Grieve (Apr 19 2019 at 13:40):
well, it's complicated. the page defines standards that should apply to all IGs. and some additional ones for HL7 publishing
Rien Wertheim (Apr 22 2019 at 18:52):
Is there / will there be an explicit distinction between the two: generic and HL7 ballotable specific?
Grahame Grieve (Apr 22 2019 at 20:10):
yes
Martijn Harthoorn (Apr 23 2019 at 08:19):
From an ISO ballot perspective what does it mean for an Implementation Guide to conform to the FHIR standard?
Martijn Harthoorn (Apr 23 2019 at 08:19):
Are we going to propose to forbid people to call their documentation an "FHIR Implementation Guide" if their home page is not called index.html?
Lloyd McKenzie (Apr 23 2019 at 14:48):
Is someone planning to ballot their IG through ISO?
Grahame Grieve (Apr 23 2019 at 20:01):
I don't think we want to forbid people to do that. the specific index.html requirement is for hl7 and fhir. But there is a general requirement there somewhere. we have to figure out what it is
Rien Wertheim (Apr 25 2019 at 09:52):
If the requirements for the HL7 ballotable IGs are different from the requirements for a FHIR IG in general, does that also imply we will have different processes for maintaining these requirements? The former lies with the FMG, the latter could be something like the FHIR ballot process itself, right?
Grahame Grieve (Apr 25 2019 at 09:53):
I'm not sure where the authority would lie. Certainly we would have wider inputs into the process
Grahame Grieve (Apr 25 2019 at 09:54):
there's actually going to be 3 levels:
- miminum for recognition as a FHIR IG
- requirements for the FHIR Community Process
- requirements for HL7 (/FHIR) publishing
Grahame Grieve (Apr 25 2019 at 09:55):
I don't know how different the first 2 are - the requirements will mainly be around the computable representation (packages, resources etc)
Grahame Grieve (Apr 25 2019 at 09:55):
I will try and restructure that page to make the 3 levels clearer (it's not clear enough now)
Martijn Harthoorn (Apr 25 2019 at 10:00):
I didn't realize before the start of this conversation that anyone wanted to place requirements on FHIR Implementation Guides in general.
But if we do want to pursue this, then it should be part of the FHIR standard - and not an internal HL7 specification.
Grahame Grieve (Apr 25 2019 at 10:17):
Yes you're probably right.
Rien Wertheim (Apr 26 2019 at 09:39):
Or just provide some guidelines and best practices for FHIR IGs in general, not having the illusion that we can ever control what people are doing with IGs when FHIR expands outside the HL7 community. With the additional advantage that we don't need a (heavy) governance model for the guidelines.
Lloyd McKenzie (Apr 26 2019 at 14:09):
I think we do a bit of both. We mandate those things that are genuinely necessary for the community to function and we define "best practices" where we think we've identified those or want to nudge towards consistency. The trick will be differentiating between those two things. It's always possible that implementers won't align with what we mandate - just as implementers choose to be non-conformant with other parts of the specification. But most will do their best to align with the SHALLs - especially if we define them sensibly.
Jose Costa Teixeira (Jun 14 2021 at 20:11):
@Nick George I think you may want to follow this stream
Nick George (Jun 14 2021 at 20:11):
cool thanks!
Last updated: Apr 12 2022 at 19:14 UTC
