Stream: IG creation
Topic: Rendering of Examples
Saul Kravitz (Nov 01 2021 at 14:15):
One area for future improvement of the IG publisher tool chain is rendering of examples.
For many of our example instances, the default renderings are not helpful to the reader, and require perusal of the JSON to really see the example content. This reduces the pedagogical value of the examples significantly.
We have resorted to workarounds like incorporating FSH-like renderings of the content as a workaround. We suggesting including an optional FSH rendering for each instance (rendered with GoFSH) in the notes section.
Similarly, the functionality of @Eric Haas tools for generating Capability Statement renderings should be incorporated into the publisher.
I have created an issue to record this request -- https://github.com/HL7/fhir-ig-publisher/issues/331.
Lloyd McKenzie (Nov 01 2021 at 14:19):
Is GoFSH sufficiently robust now we can reliably throw it against random examples? (We can't make this publishing feature dependent on the source files being maintained in FSH.)
Eric Haas (Nov 01 2021 at 14:40):
For many of our example instances, the default renderings are not helpful to the reader,
Is this assertion true for all resource types?
Eric Haas (Nov 01 2021 at 14:42):
Assuming these rendering don't requires a knowledge of FSH syntax
Saul Kravitz (Nov 01 2021 at 15:34):
@Lloyd McKenzie -- yes, the idea would be to run them against the JSON generated by Sushi since that would flatten all of the rulesets. GoFSH is pretty robust at this stage. I'm going to do the experiment on mCODE. The one issue I've found so far is that GoFSH currently generates aliases for codesystems (since that is helpful if you are going JSON to FSH for an IG). See an example here.
@Eric Haas -- currently you get a partial translation into text or the original JSON. I'm suggesting adding a full translation into FSH as an addition, not an alternative to a 'proper' text rendering. Assuming (as @Lloyd McKenzie asks) that GoFSH is robust, this is a much more scalable approach than hand rolling 'proper' renderings for each profile (including extensions, etc).
Eric Haas (Nov 01 2021 at 15:45):
so what is the proposal? another view or a replacement of the narrative view?
Jose Costa Teixeira (Nov 01 2021 at 16:02):
I'd like to explore the idea of having rendering plugins / options.
Jose Costa Teixeira (Nov 01 2021 at 16:03):
If the publisher can send the resources through some procedure and get the output from that procedure, then we woudn't worry about eventual gofsh issues
Saul Kravitz (Nov 01 2021 at 16:39):
@Jose Costa Teixeira -- no argument from me re rendering plugins/options..... can you please expand on the "eventual gofsh issues"?
Jose Costa Teixeira (Nov 01 2021 at 16:41):
we don't want tools to be too closely coupled. If gofsh has issues or if it doesn't have a good canonical form of presenting the results, publisher should not worry about that.
Jose Costa Teixeira (Nov 01 2021 at 16:45):
Eric Haas said:
so what is the proposal? another view or a replacement of the narrative view?
@Eric Haas another view, I'd guess?..
(Not that I'm too happy with the narrative view)
Lloyd McKenzie (Nov 01 2021 at 16:54):
I think having GoFSH renderings will be useful. I think having templated narratives will, in the end, produce something that's even more human-readable (and also useful for implementation), but that will take more work.
Jose Costa Teixeira (Nov 01 2021 at 17:11):
my point is: Piping stuff through GoFSH could simply be one of the templated narratives
Jose Costa Teixeira (Nov 01 2021 at 17:19):
(or one of the possible views - of which "narrative" is one)
Saul Kravitz (Nov 01 2021 at 17:20):
I think @Eric Haas may be asking where on the page the new rendering appears.
In my current effort we are sticking the FSH rendering in the 'notes' section.
Jose Costa Teixeira (Nov 01 2021 at 17:39):
In the approach I propose, the FSH rendering would show up in the "FSH" tab
Eric Haas (Nov 01 2021 at 19:13):
toggleable ( same for future YAML tab)?
David Pyke (Nov 01 2021 at 19:31):
I'm concerned that if we start having FSH or YAML tabs, people will start to assume that's legal for exchange.
Jose Costa Teixeira (Nov 01 2021 at 19:36):
Eric Haas said:
toggleable ( same for future YAML tab)?
by definition, templates (IMO) would be add-ons. I don't think there was any discussion on whether we'd allow plugins or if everything would be in the base template, in which case they'd have to be toggleable.
Jose Costa Teixeira (Nov 01 2021 at 19:41):
Keeping yaml out of the equation:
David Pyke said:
I'm concerned that if we start having FSH or YAML tabs, people will start to assume that's legal for exchange.
FSH would be a rendering. Same as if we have a diagram or any other rendering. I don't see a big additional risk.
Grahame Grieve (Nov 01 2021 at 20:40):
honestly, I hate the goFSH example provided in the task. horrible
Grahame Grieve (Nov 01 2021 at 20:40):
require perusal of the JSON to really see the example content
So? you say that like it's a bad thing...
Grahame Grieve (Nov 01 2021 at 20:41):
however:
- there's no reason people can't contribute to the rendering code
- there's no reason you can't make comment about what specifically about the rendering you think could be improved (other than 'show me the json')
Grahame Grieve (Nov 01 2021 at 20:42):
there's some tooling constraints here:
- I'm not adding another dependency to the build tooling beyond java + ruby
Grahame Grieve (Nov 01 2021 at 20:43):
note that there's two kind of rendering in the specifications:
- a hand written rendering of particular resources
- a generic profile driven renderer.
most negative comments relate to the second, but it's pretty hard to get better. References, in particular, are hard to get right in a generic fashion
Jean Duteau (Nov 01 2021 at 20:45):
Saul Kravitz said:
One area for future improvement of the IG publisher tool chain is rendering of examples.
For many of our example instances, the default renderings are not helpful to the reader, and require perusal of the JSON to really see the example content. This reduces the pedagogical value of the examples significantly.
We have resorted to workarounds like incorporating FSH-like renderings of the content as a workaround. We suggesting including an optional FSH rendering for each instance (rendered with GoFSH) in the notes section.
Similarly, the functionality of Eric Haas tools for generating Capability Statement renderings should be incorporated into the publisher.I have created an issue to record this request -- https://github.com/HL7/fhir-ig-publisher/issues/331.
@Saul Kravitz rather than doing this, why wouldn't you just add your own narrative to your examples. If you don't like the default rendering which is a hard thing to generically create, add your own narrative which will be used in the IG profile pages.
Lloyd McKenzie (Nov 01 2021 at 21:15):
YAML tab would require that YAML be a balloted form of expression for FHIR artifacts...
Hand editing narrative is challenging to keep right over time. As example data values evolve, you have to remember to change the narrative too.
Grahame Grieve (Nov 01 2021 at 21:25):
I'm ok to improve the rendering, and to invest time in it.
Saul Kravitz (Nov 01 2021 at 22:12):
@Jean Duteau Hi Jean, I'm only suggesting to make optional for others what I've done in the past (see Davinci-Plan-Net and what I'm planning to do for mCode (see example ) in the near future (assuming I have time). I think you would agree that the default rendering in the example that shows one of seven genes in a panel does not really illustrate a seven gene panel. That is my motivation, not to take pot shots at anyone or anything. Trying my best to be constructive.
Eric Haas (Nov 01 2021 at 22:16):
Lloyd McKenzie said:
YAML tab would require that YAML be a balloted form of expression for FHIR artifacts...
Hand editing narrative is challenging to keep right over time. As example data values evolve, you have to remember to change the narrative too.
... and a FSH tab would require that FSH be a balloted form of expression for FHIR artifacts too right?
Lloyd McKenzie (Nov 01 2021 at 22:19):
FSH is a balloted form of expression - for authoring. If we included a tab with it, we'd need to make clear it wasn't for exchange, but that should be doable.
Jose Costa Teixeira (Nov 02 2021 at 11:04):
Grahame Grieve said:
I'm ok to improve the rendering, and to invest time in it.
We could allow rendering that doesn't need to live in the same code base - besides the "official". This way, we'd care about the narrative, but allow other renderings. There's not going to be one soup flavour that meets everyone's taste, so we can stick to the basic rendering and allow "plugins".
Lloyd McKenzie (Nov 03 2021 at 03:43):
I believe there's now support for liquid templates for narrative?
Grahame Grieve (Nov 03 2021 at 03:44):
yes but that's pretty hard work
Lloyd McKenzie (Nov 03 2021 at 03:52):
We can push those liquid templates into the 'standard' templates if/when someone decides to do the work for a given resource.
Grahame Grieve (Nov 03 2021 at 07:22):
I spent a couple of hours on the automatic rendering for IGs:
Grahame Grieve (Nov 03 2021 at 07:24):
Saul Kravitz (Nov 03 2021 at 22:44):
For your consideration:
Here is where I think we are going with mCODE -- http://build.fhir.org/ig/HL7/fhir-mCODE-ig/branches/fshnotes2/artifacts.html#example-example-instances.
The most interesting cases are where there is a big difference between the publisher's rendering and the FSH. This happens for two reasons:
1) The publisher dereferences references to pull in additional information (e.g., bundles). FSH doesn't.
2) Where the default rendering is very limited.
Lloyd McKenzie (Nov 03 2021 at 22:57):
Given that narrative is supposed to be targeted at clinicians/patients/other 'normal' humans, I don't see how the FSH is an improvement on what we've got now. The narrative is NOT supposed to convey everything in the instance that might be of interest to developers...
Grahame Grieve (Nov 03 2021 at 23:27):
right. that's why I think that the FSH based content is going in the wrong direction. If you want to know that, look at the json
Saul Kravitz (Nov 04 2021 at 03:32):
I share your aspiration for the narrative.
Last updated: Apr 12 2022 at 19:14 UTC
