Stream: IG creation
Topic: StrucDef summary tab
Eric Haas (Mar 29 2019 at 17:37):
@Grahame Grieve or @Lloyd McKenzie can I use FHIRPath + liquid directly in the template to generate a pretty summary? Is FHIRPath enabled in the ig-pub for something like this
{% assign r = [ my current SD] %}
{% for e in r.differential.element %}
{% if e.min == 1 %}
One {{e.type}} in `{{e.path}}` {% if e.binding %} with a {{e.binding.strength}} binding to [{{e.valuesetReference.display}}]({{e.valuesetReference.reference}}){% end if %}
{% end if %}
{% end for %}
Lloyd McKenzie (Mar 29 2019 at 17:39):
Not to my knowledge...
Grahame Grieve (Mar 29 2019 at 19:11):
no that's jekyll directly
Grahame Grieve (Mar 29 2019 at 19:11):
in my plan for this year, we are working on the IG + template changes between now and montreal...
Grahame Grieve (Mar 29 2019 at 19:11):
what are our plans?
Lloyd McKenzie (Mar 29 2019 at 19:27):
My proposal:
1. You change the IGPublisher to support hitting an Ant build script with the target names we'd agreed on and be able to point at a "template" IGPackage - including the ability to merge the properties in the 'template' IG with those from the local IG files
2. I adapt my framework which is already Ant-driven and is sort of organized based on those steps already to work with the IGPublisher and we iterate until it actually runs
3. We adapt the template to accomodate capabilities that Eric's framework already has
4. We open up the template for more general feedback around appearance and capabilities (likely around the WGM)
Lloyd McKenzie (Mar 30 2019 at 15:57):
5. We create a sample IG that explains gown to create an IG using the template
6. We work to get Trifolia and Simplified to be able to publish using the template.
7. We get John or someone to adapt the template for use with IHE. (And decide if we should have a more generic template that we and others can adapt from.)
8. We get everyone to adjust their IGs to use the template prior to ballot.
In #3 we should be checking that Forge profiling will work..( @Michel Rutten I presume there's no interest from Firely in support for pure Forge- authored IGS in step 6?)
At some point in there (probably 3 or 4) we also need to rejig the IG publisher and template to support multi- version IGs.
Lloyd McKenzie (Mar 30 2019 at 16:32):
@Eric Haas?
Grahame Grieve (Mar 31 2019 at 11:05):
I'd like to talk about the authoring experience.
- examples in \examples
- other resources in \resources
- pages in \pages
Grahame Grieve (Mar 31 2019 at 11:06):
no need to register them anywhere.... that just happens through the template logic and/or the IG publsher logic
Grahame Grieve (Mar 31 2019 at 11:06):
pages as .md or .html (how are html pages templated?)
Grahame Grieve (Mar 31 2019 at 11:07):
@Jose Costa Teixeira is the logical person to work in the IHE template. Question is whether IHE wants extra facilities around actors, or whether that should also be part of the HL7 template
Grahame Grieve (Mar 31 2019 at 11:08):
Firely are certainly interested in Simplifier managed IGs, but I don't know whether they'll be interested in the template. OTOH, @Michel Rutten I will probably up the requirements for HL7 published guides to look indistinguishable from the template (not sure how I'd express that)
Jose Costa Teixeira (Mar 31 2019 at 13:31):
I think storing and managing glossaries and actors definitions are two needs from IHE that would benefit other adopters. The lifecycle for those may be more evolved in IHE - we may end up with requirements for reusing /refining actors and transactions across domains, and maintaining those over time, so that in 2025 people can still be compatible with the 2019 version...
Jose Costa Teixeira (Mar 31 2019 at 13:45):
for the folders, some ideas:
pasted image
Jose Costa Teixeira (Mar 31 2019 at 13:46):
- distinguish "test data" (which can be used to automate testing) from "examples" (that we just put there to help in documentation)?
Jose Costa Teixeira (Mar 31 2019 at 13:48):
- publisher stuff separated from the content source and output. E.g. the src-generated folder may be in all profiles I am authoring, but I don't need to have several igpublisher jars.
Jose Costa Teixeira (Mar 31 2019 at 13:50):
- can output be also a bit more structured? besides some folders for images and the likes, we could also have our css, js, etc in another folder so that we only have them once in an IHE site
Jose Costa Teixeira (Mar 31 2019 at 13:56):
Assuming this is up to date http://wiki.hl7.org/index.php?title=FHIR_IG_publisher_templates , we can play a bit with some aspects of the template:
look and feel (e.g using jekyll themes) is to be done by IHE. What pages an editor can / must author, that may also be dictated (in part).
Jose Costa Teixeira (Mar 31 2019 at 13:59):
Content wise, WYSIWYG editing is essential for non-techies. An experience like Windows Live Writer makes sense - you can edit the content itself within these lines, how it looks depends on other factors.
Jose Costa Teixeira (Mar 31 2019 at 14:03):
Anyway I don't know if .md or .xhtml makes a big difference.
From any of those we can do what we need (e.g. diff'ing and showing difference in text between 2 versions) ( theres's a tool that shows that but i forgot the name).
Jose Costa Teixeira (Mar 31 2019 at 14:06):
Tech editing will also bring some challenges - e.g. in a given edition of a profile we may include a new constraint, or 2 new supported use cases... we should find a way to track that. But I don't yet have insight on that - Not sure if this is in the realm of managing "what's new" or "requirements".
Lloyd McKenzie (Mar 31 2019 at 14:32):
If you dump everything in resources, that should work. But you should also be able to split stuff between resources, structures and vocabulary (there's good reasons to want those files separately). And if you're driving multiple IGs from one project or you've got source files you don't necessarily want in your IG yet, you'll need to register the files in the IG. You'll also need to register the files in the IG if you want control over what packages exist and what's in each package. However, the names and descriptions should come across automatically.
Lloyd McKenzie (Mar 31 2019 at 14:32):
You'll have to register your pages as that's the only way to determine titles and hierarchy.
Lloyd McKenzie (Mar 31 2019 at 14:33):
Pages will have to support md and html (because either Eric or I will throw a screaming fit if our favorite isn't permitted and there are people who will want both kinds)
Lloyd McKenzie (Mar 31 2019 at 14:36):
I would hope that Simplifier would be capable of exporting to allow the use of templates - if not, they'll find themselves not useable for HL7 balloted content, IHE balloted content or that of anyone else who wants tight look-and-feel of their IGs. After a while, that's going to take a good chunk out of their market... (The look & feel of evey type of template will evolve over time and I'm pretty sure HL7 is going to mandate consistent look & feel across all our IGs - which means they're all going to have to publish using the same template.)
Lloyd McKenzie (Mar 31 2019 at 14:39):
@Jose Costa Teixeira We could have a 'testing' folder. Disagree about not needing several igpublisher.jars. You may well find that you want to publish some IGs with one version of the publisher and others with a different one for some reason. The template itself could be shared (via the NPM cache), but not sure about the publisher
Lloyd McKenzie (Mar 31 2019 at 14:40):
I'd really like 'output' to be renamed 'website' because it's logical to have the stuff produced at the end of the directory structure, not in the middle.
Lloyd McKenzie (Mar 31 2019 at 14:40):
output being structured is a pia because you then have to worry about relative folders for everything which dramatically complicates your folders.
Lloyd McKenzie (Mar 31 2019 at 14:41):
WYSIWYG is an authoring tool problem, not a publisher problem.
Lloyd McKenzie (Mar 31 2019 at 14:43):
As a side note - every time I've had to use markdown, I've had to embed a bunch of funky markdown escapes and commands to make it work right, which to me means that it's not significantly less complicated to learn than XHTML, with the downside that there's no schema or built-in validation when authoring, and worse, the markdown we author the pages in is different the markdown we author the attribute descriptions in, so it doesn't work exactly the same.
Jose Costa Teixeira (Mar 31 2019 at 15:05):
You'll have to register your pages as that's the only way to determine titles and hierarchy.
That would be for the authoring toolset (to create an IG including page structure) (unless i miss the topic)
Jose Costa Teixeira (Mar 31 2019 at 15:07):
Pages will have to support md and html (because either Eric or I will throw a screaming fit if our favorite isn't permitted and there are people who will want both kinds)
agree with both formats (just because they should be convertible)
Jose Costa Teixeira (Mar 31 2019 at 15:08):
Disagree about not needing several igpublisher.jars. You may well find that you want to publish some IGs with one version of the publisher and others with a different one for some reason. The template itself could be shared (via the NPM cache), but not sure about the publisher
You may need to have several igpublishers, but IMO you don't want to be forced to. I think when building we should be able to point to the IG Publisher, instead of letting it "whatever you find under this folder"
Lloyd McKenzie (Mar 31 2019 at 15:11):
There might or might not be an authoring toolset. Assuming no tool, the user will have to hand-author their ImplementationGuide instance, which will need to include references to the pages (and describe their titles and hierarchies). If authoring tools take on this function, great.
Lloyd McKenzie (Mar 31 2019 at 15:12):
md and XHTML will not be convertable. (At least I can't begin to imagine trying to turn XHTML into markdown). Jekyll handles turning the markdown into XHTML.
Jose Costa Teixeira (Mar 31 2019 at 15:12):
output being structured is a pia because you then have to worry about relative folders for everything which dramatically complicates your folders.
what structure? The authored .pngs, htmls...? or the .css and .js that come with the framework? For the latter, would still be nice to configure where they are found (e.g. i could say ../../styles) and then all my profiles can reuse those.
Lloyd McKenzie (Mar 31 2019 at 15:13):
I don't see a huge problem in multiple igpublishers, other than the download time if you don't have the current one.
Lloyd McKenzie (Mar 31 2019 at 15:13):
The styles from the template will be inside the template. IG authors won't see those - or generally be able to fiddle with them.
Lloyd McKenzie (Mar 31 2019 at 15:14):
In the output folder, their location won't be configurable and content will generally be pretty flat.
Jose Costa Teixeira (Mar 31 2019 at 15:18):
Multiple IGs are not a huge problem, but I don't see big advantages. I'd separate the machine, the input and the output. Makes it more manageable. It's minor (but I did some scripting to fix that on my end, so it was inconvenient).
Lloyd McKenzie (Mar 31 2019 at 15:20):
My concern is that the folder that defines an IG should be self-contained. It shouldn't touch anything outside its folder other than the NPM cache. Doing that causes too much risk of accidentally messing things up
Jose Costa Teixeira (Mar 31 2019 at 15:20):
I guess for md and html I guess my preference is: as long as a user can do something that somehow ends in either or both, we are good.
Pandoc supports both outputs, but I haven'd played with it enough to see how good it looks.
Lloyd McKenzie (Mar 31 2019 at 15:21):
It won't end in md ever. The publication will have to be html.
Jose Costa Teixeira (Mar 31 2019 at 15:23):
ok, so it is just about if we want to have the publisher accepting md as well? I don't have a preference.
At this moment I have Word editing and Pandoc converting to xhtml, so anything should be manageable.
Lloyd McKenzie (Mar 31 2019 at 15:24):
Yes. Question is what can serve as input. And realistically, we'll need both.
Jose Costa Teixeira (Mar 31 2019 at 15:27):
makes sense.
Jose Costa Teixeira (Mar 31 2019 at 15:30):
Oh, and one more requirement that IHE and similars may have: National extensions. Things like translations - of glossaries, of actor names, etc.
Here's a hypothetical: When IHE Belgium wants to publish some stuff, this may require up to 4 languages (EN+NL+FR+DE).
Lloyd McKenzie (Mar 31 2019 at 15:39):
I suspect support for multi-language IGs will not be a "before next ballot" sort of change. That's going to require some significant thought and infrastructure.
Jose Costa Teixeira (Mar 31 2019 at 15:44):
yes. It is a requirement, definitely not a priority.
Grahame Grieve (Mar 31 2019 at 20:46):
there is some structure for multi-language IGs but it won't be in this round, that's certainly correct
Grahame Grieve (Mar 31 2019 at 20:46):
md and html will both be supported.
Grahame Grieve (Mar 31 2019 at 20:47):
we will continue with the arrangement as is: one IG per github repository.
Grahame Grieve (Mar 31 2019 at 20:48):
I don't want to rename output to website. Lloyd's desire to have a particular order in the folders does not justify the changes to tooling, documentation and bookmarks that this would cause
Grahame Grieve (Mar 31 2019 at 20:49):
All the css etc should be in the template; the IG should contain only content - resources and pages
Grahame Grieve (Mar 31 2019 at 20:51):
you should also be able to split stuff between resources, structures and vocabulary (there's good reasons to want those files separately)
What are those?
Grahame Grieve (Mar 31 2019 at 20:52):
if you're driving multiple IGs from one project or you've got source files you don't necessarily want in your IG yet, you'll need to register the files in the IG
Neither seem like a good to force people to register all their resources
Lloyd McKenzie (Mar 31 2019 at 22:05):
The people responsible for vocabulary, resources and other stuff are often different people. Forge likes having all the resources in one place but isn't going to recognize the other stuff. When you start getting large numbers of artifacts (into the hundreds), it's a lot easier if everything isn't all stuck in one folder. (And yes, I have IGs that have that volume of artifacts).
Lloyd McKenzie (Mar 31 2019 at 22:06):
I'm not suggesting the people will have to register their resources - if they want all of them, they'll get all by default. But if they don't want all of them, they'll have the option of registering them to choose what they want and/or to choose what packages they'll appear in.
Lloyd McKenzie (Mar 31 2019 at 22:07):
I.e. if your IG doesn't list any resources, the build will look to find all the candidates and group them in packages based on criteria we decide and will publish all of them. If your IG does list resources, we'll use the packages you define and include the resources you reference and nothing else.
Lloyd McKenzie (Mar 31 2019 at 22:08):
If you dump all of your resources in "resources", that'll work. If you split them between "resources", "structures" and "vocabulary", that'll still work.
Grahame Grieve (Mar 31 2019 at 22:09):
ok where are we documenting this stuff ?
Lloyd McKenzie (Mar 31 2019 at 22:10):
Where do you want it?
Lloyd McKenzie (Mar 31 2019 at 22:10):
Eric and I had a Google doc we took a stab at a good while back?
Grahame Grieve (Mar 31 2019 at 22:12):
I'm happy to work it up there as long as it migrates to the HL7 wiki once it's mature
Lloyd McKenzie (Mar 31 2019 at 22:15):
My desire is that the final documentation actually be in a FHIR IG that uses the template to document itself.
Grahame Grieve (Mar 31 2019 at 22:16):
hah well ok. if you want to do it that way...
Lloyd McKenzie (Mar 31 2019 at 22:16):
That sort of forces it to be kept up-to-date as the publisher evolves and provides a concrete example of everything that's being done.
Lloyd McKenzie (Mar 31 2019 at 22:26):
In terms of output, I don't understand there being any changes to bookmarks - unless you bookmark your local output? All the documentation is changing anyhow, so don't much care about that. In the tooling, it should just be a change of a constant in the publisher and in the CI build process. I think it's at least worth evaluating the level of effort before rejecting it out-of-hand.
Grahame Grieve (Mar 31 2019 at 22:29):
lots of people have booked marked their local outputs
Grahame Grieve (Mar 31 2019 at 22:30):
the IG publisher has nothing hard coded about output. The CI build does. And lots of my batch files for publishing does
Jose Costa Teixeira (Apr 01 2019 at 04:43):
On glossary definitions, I prefer that any profile author can create (propose) new terms or changes to terms.
Lloyd McKenzie (Apr 01 2019 at 04:45):
@Jose Costa Teixeira Not sure what this is referring to or what it has to do w/ IG publication
Jose Costa Teixeira (Apr 01 2019 at 04:47):
I agree that people responsible for those and other resources may be different but an editor needs to define actors, glossary terms, etc - all of them. I see no interest if we aim at e.g. separate ig for glossary
Lloyd McKenzie (Apr 01 2019 at 04:58):
Artifacts can only live in one place. If you're maintaining a glossary (as a web page or something), that glossary can only exist in one IG. You can link to it from any IG you like (if you declare the owning IG as a dependency), but you can't edit a definition defined in one IG within another IG.
Jose Costa Teixeira (Apr 01 2019 at 04:59):
It was an interpretation of your above statement "people responsible for vocabulary.. are different people" - possibly confusion from my side.
Jose Costa Teixeira (Apr 01 2019 at 05:00):
Artifacts can only live in one place. If you're maintaining a glossary (as a web page or something), that glossary can only exist in one IG. You can link to it from any IG you like (if you declare the owning IG as a dependency), but you can't edit a definition defined in one IG within another IG.
Hmmm. I will draw up the glossary management workflow. Key point is - say there is an IHE glossary, which is the set of "approved" entries that people from many domains have proposed
Jose Costa Teixeira (Apr 01 2019 at 05:02):
So anyone can propose such a thing, it then has to go for approvals. But this will be common requirement - imo an IG will not only be approved as a whole, but the artefacts within will be reviewed and approved
Jose Costa Teixeira (Apr 01 2019 at 05:03):
This question is not about how to use the IG for editing. This is more about making sure that any editing can then be used in a process with more or less collaboration, more or less gateways...
Jose Costa Teixeira (Apr 01 2019 at 05:05):
We just need to enable that (with simple things like status and keeping glossary terms and actors as resources)
Grahame Grieve (Apr 01 2019 at 05:08):
terminology = code system, value set , concept map
Jose Costa Teixeira (Apr 01 2019 at 05:15):
Yes, and we need a glossary (where things like "dispense" have a clear definition. Should be a valueset
Lloyd McKenzie (Apr 01 2019 at 05:15):
The feedback process is separate from the development/publication process. People won't make proposals by submitting edits to the source (unless they're making Git pull requests - and in HL7 those still need to be accompanied by a tracker item).
Lloyd McKenzie (Apr 01 2019 at 05:16):
ValueSet is for formally defined codes intended for computation. Seems like overkill to use such an artifact just to maintain a list of defined terms for human use. Why not just a page of markdown?
Lloyd McKenzie (Apr 01 2019 at 05:16):
(or better yet, HTML :))
Jose Costa Teixeira (Apr 01 2019 at 05:17):
Use case: as an IHE profile editor, I want to reuse the term "patient" in my profile, but I want to define "dispense" which is not defined in the IHE common glossary. So I add a resources for that, status =draft. If all goes well, after a few gates, the profile is published and the term "dispense" becomes part of the approved glossary for IHE so that others can use it.
Lloyd McKenzie (Apr 01 2019 at 05:24):
Why not just submit a change request to the main glossary and define the term as you need in your own in a supplemental glossary page for as long as needed. Why bother creating an artifact?
Jose Costa Teixeira (Apr 01 2019 at 05:25):
(Sorry for rabbit hole, back to topic). A few weeks ago we(IHE) discussed working on IHE specific requirements. will put them somewhere.
Michel Rutten (Apr 01 2019 at 11:22):
@Lloyd McKenzie & @Grahame Grieve can we discuss the proposed improvements of the IG template during a WGM session? We like to update the Simplifier template to comply to the new, updated guidelines. I don't think this will affect Forge. (@Martijn Harthoorn)
Grahame Grieve (Apr 01 2019 at 11:54):
sure we can do that
Grahame Grieve (Apr 01 2019 at 11:55):
but most of the big decisions will be made by then
Martijn Harthoorn (Apr 01 2019 at 12:33):
I would hope that Simplifier would be capable of exporting to allow the use of templates - if not, they'll find themselves not useable for HL7 balloted content, IHE balloted content or that of anyone else who wants tight look-and-feel of their IGs. After a while, that's going to take a good chunk out of their market... (The look & feel of evey type of template will evolve over time and I'm pretty sure HL7 is going to mandate consistent look & feel across all our IGs - which means they're all going to have to publish using the same template.)
Martijn Harthoorn (Apr 01 2019 at 12:33):
I am not so much worried about our chunk in the market. But I am concerned about general usability.
Martijn Harthoorn (Apr 01 2019 at 12:34):
It is unclear to me which part of this proces is part of the FHIR standard.
Martijn Harthoorn (Apr 01 2019 at 12:34):
And how much is part of a request of HL7 to have other tools produce imput compatible with their tools
Martijn Harthoorn (Apr 01 2019 at 12:37):
I would love to advice our users and customers create ballotable IG's. But currently I wouldn't know how to provide them with a clear and predictable strategic advice.
Grahame Grieve (Apr 01 2019 at 12:56):
that's an ongoing discussion we should continue at Montreal. The template is 2 things - a publishing convenience and a fixed look and feel for the IGs. The first part is not important for Simplifier. The second part will be required for anything published through HL7, but meeting that look and feel won't necessarily require actually using the template
Chris Moesel (Apr 01 2019 at 13:06):
Just inserting myself into the conversation to note that we publish IGs at MITRE using our CIMPL tooling -- and I'm all for simplification of publishing via easier to use templates. We already make it as simple as possible for our users, but that just makes our own code a bit more complicated -- and speaking from experience, it did take me a while to get that all working correctly. So if we can lower the barrier for others, I think that would be a good thing. And I'll gladly replace my code with a better and easier template. ;-)
Lloyd McKenzie (Apr 01 2019 at 14:08):
My suspicion is that meeting the look and feel without using the template - especially as the look and feel evolves over the next few years - will be challenging.
John Moehrke (Apr 01 2019 at 14:41):
Note that @Jose Costa Teixeira has the lead on use of the HL7 IG publisher for IHE. I am just the co-pilot.
Eric Haas (Apr 01 2019 at 22:21):
I have to digest what Lloyd outlined above before I can chime in here. I think that the fixed look and feel that GG mentions is important but equally important is on making it easier publish without being an expert in html, jekyll, liquid , json or xml, or (your programming language here). Still too may knobs and switches and we need start limiting the options.
Lloyd McKenzie (Apr 02 2019 at 02:53):
So long as the default options are easy, I'm not sure we need to limit things too much. We can't stop people from authoring instances in the syntax they're most comfortable with, so XML or JSON will always be there - though I'm hoping we can find a way to let them embed references to examples in their text so that they don't have to mess around with escaping unvalidatable JSON or XML inline. Similarly, we can't avoid the need for some level of liquid tags to get the directories right. But hopefully we can limit the need to know too much more.
Eric Haas (Apr 02 2019 at 03:48):
OK so I finally tried your ig pub framework and I struggled to convert my test ig over to it. It requires the manual creation of an Implementation guide resource. I don't think that is an author friendly approach. I think the Implementation guide resource input needs to be a UI form or excel driven. ( I generated the ig.json and ig.xml from a csv and slurp up the fhir artifacts from the folders)
We are in agreement the file tree needs to be fixed and prescribed, I think it should evolve so it drives the ig menu and page structure. (Which I think will make GG unhappy) I.e it should align with Jekyll. ( but need watch out for messing up the includes)
I think the layouts ( layouts ~= templates ) are the easiest thing about this. Pretty straight forward obviously is a matter of taste and Obvously I like mine better :-) ...but once we decide on layouts they hopefully can be ordered up like a menu item. As far as authoring in md or html that should be slurped up from the folder/ file name so its in the background. ( same with the xml,json, xls for fhir artifacts), I wonder if Chris has done all of this already?
I'm pretty neutral on the ant thing. I'm not clear why it needs to be part of the ig-pub.
Jose Costa Teixeira (Apr 02 2019 at 04:13):
On layouts: I would like to experiment with themes, so that people can have different look and feel or just print-friendly templates.
Lloyd McKenzie (Apr 02 2019 at 15:00):
Going forward, the ImplementationGuide resource is the bit that will have to be created. There won't be any JSON files anymore. Everything will be done through the ImplementationGuide (though much of the 'hard' stuff will be imported from an ImplementationGuide in the template).
Lloyd McKenzie (Apr 02 2019 at 15:01):
I think the menu and the table of contents should be independent. They're different navigational frameworks and there's good reasons for them to work differently. The menu often needs to have links to external specs. The TOC won't.
Lloyd McKenzie (Apr 02 2019 at 15:03):
The UI for IG authoring is out of scope. If you use a tool like Trifolia, it should take care of it for you. If we want to come up with a way to author IGs using a spreadsheet, we can, though not sure how enthused Grahame will be about that. (We do need to add the spreadsheet re-writing thing into the IGPublisher for structure definitions at least so they work better with Git).
Lloyd McKenzie (Apr 02 2019 at 15:04):
Personally, I don't think hand-authoring IGs is so bad. We already expect hand-authoring of examples, so familiarity with XML or JSON is essentially mandatory if you're creating IGs anyhow.
Lloyd McKenzie (Apr 02 2019 at 15:07):
I'm fine with some experimentation with layouts, so long as we land on a standard layout that's used by all the HL7 IGs. Certainly additional templates will be needed for those that want PDFs or something. I don't think HL7-published IGs should cater to that.
Lloyd McKenzie (Apr 02 2019 at 15:08):
Ant is a pretty natural mechanism for dependency-based file processing that can happen in stages which is what we agreed the IGPublisher templates needed to allow - to perform file processing at different stages of the publishing process.
Eric Haas (Apr 02 2019 at 16:33):
I think that authoring the ImplementationGuide, CapabilityStatement and Structuredefs are off putting for ig authors and hard without tooling. External tooling already exists for SDs, and is needed for Capstatements, but I think ImplementationGuide tooling needs to be part and parcel to the ig pub process an a ui form/( or excel) for ease of Authoring. I do it before calling the ig-pub using bash. I'm not sure why the ant script needs to be part of the the ig-pub. I can see calling it multiple times in a single script but I don't really care either way.
To be precise the ImpGuide template is different template from the Jekyll layouts/templates.
I don't know why the file tree can't mimic the menu and TOC and I don't think external links should be menu items . This is an example of limiting the options to make it simpler and more uniform.
Lloyd McKenzie (Apr 02 2019 at 17:38):
Tooling would be great, but it's a separate thing from the template process.
Lloyd McKenzie (Apr 02 2019 at 17:39):
I don't want simpler/more uniform that's less useful to the target audience. The external links in CRD are quite important and having an easy way to get to them all the time is needed. Menu and TOC are both navigation tools. Having them say exactly the same thing means that you're not really getting the benefit you should.
John Moehrke (Apr 02 2019 at 17:41):
infrastructure and template are far more important than tooling for the editors. That tooling should be encouraged an happen, but should not be mandate.
Lloyd McKenzie (Apr 02 2019 at 17:41):
The reality is that creating implementation guides is always going to require a degree of technical chops for at least one of the people involved in the process. You're going to be creating instance examples. You're going to be dealing with commandline tools that sometimes spit out cryptic errors. You're going to be dealing with Git.
John Moehrke (Apr 02 2019 at 17:41):
I agree with Lloyd that the editors today can handle simple xhtml, xml, and json. We should not be afraid of those.
Lloyd McKenzie (Apr 02 2019 at 17:41):
You're going to have to understand code systems vs. value sets and how to do thos properly.
Lloyd McKenzie (Apr 02 2019 at 17:42):
If they can't hand-author an ImplementationGuide that says "here are my pages and their hierarchy", how are they supposed to hand-edit a prescription or diagnostic report?
Grahame Grieve (Apr 02 2019 at 19:06):
external tooling exists for editing capability statement in R3 and R4
Grahame Grieve (Apr 02 2019 at 19:08):
the template should start from IG and assume that tooling will grow around that. Forge already includes an IG editor, so we should assume that @Michel Rutten will update to the current version
Lloyd McKenzie (Apr 02 2019 at 19:10):
Firely has indicated they don't plan to do much investment in the IG capabilities of Forge - they see that as more of a Simplifier function
Grahame Grieve (Apr 02 2019 at 19:11):
well, perhaps someone else will then. Or perhaps we'll sort things out with simplifier...
Grahame Grieve (Apr 02 2019 at 19:11):
I mean, we will, I expect. The issue with simplifier is basically about templating
Eric Haas (Apr 02 2019 at 19:33):
Well after doing this for a while, I still think HL7 Ig publishing is too hard and the first step is making the onboarding with ImplementationGuide easy peasy. I don't think hand authoring examples should be a prereq.
Grahame Grieve (Apr 02 2019 at 19:34):
it's purely a format issue, right? there's nothing you have to say in an IG that you don't have to say anyway...
David Pyke (Apr 02 2019 at 19:35):
Using the spreadsheets and manual creation/updating of the other IG files didn't seem to be difficult. There is definitely room to move to tooling from spreadsheets but at this point, it seemed to be fairly straightforward but time consuming
Eric Haas (Apr 02 2019 at 19:48):
If we think the authors need to be experts in hand authoring resources in all the formats, creating markdown and xhtml ( and I would add here YAML files) then all we need to do is decide on the templates and we are good to go.
Grahame Grieve (Apr 02 2019 at 19:50):
why all formats? they can just pick one.
Grahame Grieve (Apr 02 2019 at 19:50):
and we can assume tooling will come. Of course, editors can choose not to use the tooling that already exists
Grahame Grieve (Apr 02 2019 at 19:52):
like, for instance, there is already an IG editor
Grahame Grieve (Apr 02 2019 at 19:52):
for R4
Lloyd McKenzie (Apr 02 2019 at 19:53):
No need for them to know anything about YAML. They can pick one of markdown or XHTML (though knowing a bit of XHTML is useful even for the markdown folks as sometimes markdown won't do what you need). For the resources you need to know XML or JSON but don't need the other. Perhaps someday we'll have a tool suite that will protect authors from all that, though to be honest, I'm not sure how much I'd trust an IG that was written by someone who can't hand-edit an XML or JSON instance. How can you write something targeting developers if you don't have some basic technical chops?
Grahame Grieve (Apr 02 2019 at 19:54):
depends on what kind of guide you are writing. the type we are doing now, you're right. purely domain content things later.... not so much
Lloyd McKenzie (Apr 02 2019 at 19:56):
If the purely domain content has technical impact on real code, then there should be at least someone in the mix who understands the ramifications of that impact. At least if the implementation guide is going to be appropriate to actual "implementation" :)
Eric Haas (Apr 02 2019 at 20:00):
If we expect authors to be capabable of providing IG artifacts in completed form then why do we need 1,2,3?
I think we just hash how the look and feel of the templates?
"
Lloyd McKenzie: My proposal:
1. You change the IGPublisher to support hitting an Ant build script with the target names we'd agreed on and be able to point at a "template" IGPackage - including the ability to merge the properties in the 'template' IG with those from the local IG files
2. I adapt my framework which is already Ant-driven and is sort of organized based on those steps already to work with the IGPublisher and we iterate until it actually runs
3. We adapt the template to accomodate capabilities that Eric's framework already has
4. We open up the template for more general feedback around appearance and capabilities (likely around the WGM)
Lloyd McKenzie: 5. We create a sample IG that explains gown to create an IG using the template
6. We work to get Trifolia and Simplified to be able to publish using the template.
7. We get John or someone to adapt the template for use with IHE. (And decide if we should have a more generic template that we and others can adapt from.)
8. We get everyone to adjust their IGs to use the template prior to ballot.
In #3 we should be checking that Forge profiling will work..( @Michel Rutten I presume there's no interest from Firely in support for pure Forge- authored IGS in step 6?)
At some point in there (probably 3 or 4) we also need to rejig the IG publisher and template to support multi- version IGs.
"
Lloyd McKenzie (Apr 02 2019 at 20:04):
We want there to be a single template that everyone in HL7 uses that's maintained in a separate Git project from the actual IG content. (Similarly IHE will have a single template, NICTIZ will have a single template, etc.)
Grahame Grieve (Apr 02 2019 at 20:05):
feedback form the authors is really strong: we do resources. the ins and outs of stitching html and managing path destinations is a pig.
Grahame Grieve (Apr 02 2019 at 20:05):
and maintaining a consistent look and feel is too hard.
Lloyd McKenzie (Apr 02 2019 at 20:05):
Plus the variations in appearance and approach are a problem for the reviewers and implementers.
Grahame Grieve (Apr 02 2019 at 20:06):
so that's the main focus of the template work
Eric Haas (Apr 02 2019 at 20:06):
so why 1,2 that has nothing to do with template and everything to do with ImplementationGuide building?
Lloyd McKenzie (Apr 02 2019 at 20:06):
That's what allows an IG to point to a template defined somewhere else.
Grahame Grieve (Apr 02 2019 at 20:07):
y
Eric Haas (Apr 02 2019 at 20:11):
I've done that locally for the last two years split the source from the framework, but the autobuilder requires the framework and the source to be in the same repo so I'm stuck having to merge them back to get published
. It is pain in Git to have remote modules too so I only push the source and the output (for git pages) is that what you are talking about? splitting the source repro from the framework?
Grahame Grieve (Apr 02 2019 at 20:13):
sort of but not exactly like that.
Grahame Grieve (Apr 02 2019 at 20:14):
there'll be a git repository that has the template - simliar to the framework. we'll do releases from the repo using NPM packages. and then you just nominate the npm package in your ig, and create the content you want
Eric Haas (Apr 02 2019 at 20:29):
OK so the magic happens and
templates take care of "the ins and outs of stitching html"
"maintaining a consistent look and feel is too hard." means limited options in the standard template - you can't have both imo
"and managing path destinations is a pig." I don't see how this will fix that.
Eric Haas (Apr 02 2019 at 21:01):
Ok so where are we on source file tree structure, I don't see a way to to indicate file's paths source in the IG resource. that is all in ig.json right now. I want to use it to drive building my ImplementationGuide. I assume it will need to be fixed.
Lloyd McKenzie (Apr 02 2019 at 21:04):
The IG resource won't indicate file paths. The template will indicate what folders to check for which kinds of things and the files will need to adhere to a naming standard.
Lloyd McKenzie (Apr 02 2019 at 21:05):
If you identify the artifacts in the IG, it'll be by canonical URL - and it'll be an error if the IGPublisher doesn't find exactly 1 file for the specified canonical URL.
Grahame Grieve (Apr 02 2019 at 21:09):
I'm not sure about that bit.
Grahame Grieve (Apr 02 2019 at 21:10):
but the easiest way to maintain the IG for me is to tell the IGPublisher what files to look for resources in, and let it load and register them
Eric Haas (Apr 02 2019 at 21:12):
The template will indicate what folders to check for which kinds of things and the files will need to adhere to a naming standard. ???
Why not make the part of the ig resource - its there for pages?
Lloyd McKenzie (Apr 02 2019 at 21:15):
Actually, it's not fully there for pages either - you specify a name but not a full path.
Lloyd McKenzie (Apr 02 2019 at 21:16):
In the end, the IG resource needs the canonical URLs. Given that we can make it work without the filenames, not sure why we'd add the extra overhead.
Lloyd McKenzie (Apr 02 2019 at 21:17):
Also, it removes the temptation to name the source files in non-standard ways, which makes maintenance easier for Grahame and others who might have to come in and tweak someone else's IG
Eric Haas (Apr 02 2019 at 21:17):
<nameUrl value="index.html"/> looks like a relative path to me
it sounds like we are moving ig.json to the template bundle.
Lloyd McKenzie (Apr 02 2019 at 21:18):
index.html doesn't exist in the root of the IG folder. It lives in one of the folders where the template says to look for page files
Grahame Grieve (Apr 02 2019 at 21:19):
not all resources have canonical urls
Eric Haas (Apr 02 2019 at 21:19):
yes i get that part. but is could be <nameUrl value="my_path/index.html"/>
Grahame Grieve (Apr 02 2019 at 21:20):
that's what the point of name[x] is
Eric Haas (Apr 02 2019 at 21:27):
@GG
that's what the point of name[x] is
is that in response to my comment or Lloyds?
we have in ig.json plus a path list where to find things . This doesn't seem hard to find the source file no matter how you name it.
...
"paths": {
...
"resources": [
"source/resources",
"source/examples"
]
...
"Patient/example2": {
"source": "foo.xml",
"base": "Patient-example2.html"
How is it going to be represented in the template package ?
Eric Haas (Apr 02 2019 at 21:31):
and when Lloyd says template I think of this below and I'm not certain that is what you are talking about because I'm not seeing a way to have paths and file names here....
---
# jekyll header
level: 2
template: base
active: format
layout: fhir-artifact
type: {{[type]}}
id: {{[id]}}
topofpage: True
---
<!-- ig template for many conformance resource html pages ('base' in definitions file) can not be used for conformance resources that have more that a single base template. e.g., sd since there are mapping and definitions templates for it as well they need to be split out into 3 separate templates -->
<!-- ============ CONTENT CONTENT=============== -->
{% case '{{[type]}}' %} <!-- content depends on type -->
{% when 'ValueSet' %}
<!-- ============VAlUESET CONTENT CONTENT=============== -->
{% include {{[type]}}-{{[id]}}-summary.xhtml %}
{% include {{[type]}}-{{[id]}}-xref.xhtml %}
{% include {{[type]}}-{{[id]}}-cld.xhtml %}
<h3>Expansion</h3>
{% include {{[type]}}-{{[id]}}-expansion.xhtml %}
<!-- ============VAlUESET CONTENT CONTENT=============== -->
{% when 'CodeSystem' %}
<!-- ============CODESYSTEM CONTENT CONTENT=============== -->
.....
Jose Costa Teixeira (Apr 03 2019 at 04:08):
I mentioned the location of the source files in the extra session we had during the last WGM - my problem was: how do we keep an ig.xml attached to the other source files. Or how do we pack all those files (which are the only thing that we need to send over between editors, for review).
Jose Costa Teixeira (Apr 03 2019 at 04:08):
a) ig.xml is also in the source/resources folder like the others
b) ig.xml is on the folder that contains the source
Grahame Grieve (Apr 03 2019 at 04:11):
you should always use version control to share between editors
Jose Costa Teixeira (Apr 03 2019 at 04:16):
ok, meanwhile i got that covered. but i used option b above.
Lloyd McKenzie (Apr 03 2019 at 04:16):
You should use version control even if you're the only editor :)
Jose Costa Teixeira (Apr 03 2019 at 04:18):
yes. i could only live with that after providing a decent way for non technical users to do it. if i send an email to a pharmacist to review an IG, i have to use words like "please", not words like "install git" :)
Grahame Grieve (Apr 03 2019 at 04:20):
should be using continuous build -that's how we handle that - commit and say 'look here on the web'
Jean Duteau (Apr 03 2019 at 04:21):
yeah, you shouldn't be sending the source files to people who can't run the publisher themselves. you want them to review the actual IG not the source - which would be a combination of markdown, XML, JSON, etc.
Jose Costa Teixeira (Apr 03 2019 at 04:33):
review = revise
Jose Costa Teixeira (Apr 03 2019 at 04:35):
it seems i can safely move with option b then.
Jose Costa Teixeira (Apr 03 2019 at 04:37):
pasted image
option b is this.
Rien Wertheim (Apr 08 2019 at 12:13):
I would hope that Simplifier would be capable of exporting to allow the use of templates - if not, they'll find themselves not useable for HL7 balloted content, IHE balloted content or that of anyone else who wants tight look-and-feel of their IGs. After a while, that's going to take a good chunk out of their market... (The look & feel of evey type of template will evolve over time and I'm pretty sure HL7 is going to mandate consistent look & feel across all our IGs - which means they're all going to have to publish using the same template.)
This is not so much about marketshare, but about keeping the FHIR tooling ecosystem aligned. Please keep in mind:
- That we already have a WYSIWYG IG editor built in in Simplifier
- That we have an agreement in place with HL7 that allows all users and authors of HL7 ballotable content to use the Enterprise account of HL7 on Simplifier. This includes numerous advanced features. Always happy to do a demo if you're interested
- That we recognize the need for IG alignment and that we have a master template for HL7 ballotable content available on Simplifier
- That we have regular meetings with @Wayne Kubick and @Grahame Grieve around the HL7 and Firely tooling for the purpose of alignment.
We recommend a clear separation between the spec and the IG guidelines on the one hand, and the tooling on the other hand.
Grahame Grieve (Apr 09 2019 at 07:06):
e.g. this is still work in progress. Simplifier need not support the actual same template, but does need to meet HL7 publishing requirements.
Last updated: Apr 12 2022 at 19:14 UTC
