Stream: committers
Topic: New IG templates
Lloyd McKenzie (May 17 2021 at 16:24):
@John Moehrke You can see an example of the dragon here: http://build.fhir.org/ig/HL7/fhir-cdisc-mapping/branches/main/overview.html
John Moehrke (May 17 2021 at 16:35):
I have an stu-note use, I changed it to dragon, but it didn't work. Not sure if this is IHE template thing?
John Moehrke (May 17 2021 at 16:42):
is there a confluence page that explains these defined class ?
John Moehrke (May 17 2021 at 16:46):
it worked in a non-IHE project. So this must be something that @Jose Costa Teixeira needs to bring into the IHE template.
Lloyd McKenzie (May 17 2021 at 17:11):
It's defined in the base template. If Jose has completely overridden the project CSS in the IHE template, then it wouldn't work. Perhaps we could split the 'standard' CSS into the parts Jose wants to override and the parts he doesn't?
Jose Costa Teixeira (May 17 2021 at 17:15):
the IHE template overrides project.css completely, there's no split yet (at the time it was created this was not easy), but i plan to trim down the project.css
John Moehrke (May 18 2021 at 12:03):
@Brett Marquard @Eric Haas here for discussion of new IG build template
John Moehrke (May 18 2021 at 12:04):
here is where they are vetted
John Moehrke (May 18 2021 at 12:04):
I like the next/prev.. it might be made better over time, but it is a fantastic MVP
Brett Marquard (May 18 2021 at 12:09):
Thanks for the @. It's not clear to me the 'next/prev' is useful in an IG that doesn't read like a book.
Brett Marquard (May 18 2021 at 12:09):
Where is the list of features for this release, prior release, proposed future relase?
Brett Marquard (May 18 2021 at 12:10):
US core isn't intended to be flipped through like a PDF.
John Moehrke (May 18 2021 at 12:11):
having next/prev does not mandate that someone page thru
John Moehrke (May 18 2021 at 12:11):
but having a consistant way that one could, is a good thing
John Moehrke (May 18 2021 at 12:12):
I have a purely vocabulary based IG.. also not useful to page thru... but I don't mind
John Moehrke (May 18 2021 at 12:13):
I often find that my intent for how it should be read, is different than some readers desire to read
Brett Marquard (May 18 2021 at 12:17):
I think the next/previous implies we have a desired flow for the reader -- which isn't true. if you want to read about provenance in US Core, should you read about 'Medication' and 'clnical Notes' first?
Brett Marquard (May 18 2021 at 12:18):
For US Core, I don't expect them to be helpful for any new/experienced reader. I think they are noise....but I a missing where the discussion was had to add?
John Moehrke (May 18 2021 at 12:20):
Brett Marquard said:
I think the next/previous implies we have a desired flow for the reader -- which isn't true. if you want to read about provenance in US Core, should you read about 'Medication' and 'clnical Notes' first?
I disagree that this implication is fact.
John Moehrke (May 18 2021 at 12:20):
Brett Marquard said:
For US Core, I don't expect them to be helpful for any new/experienced reader. I think they are noise....but I a missing where the discussion was had to add?
here, now
Brett Marquard (May 18 2021 at 12:21):
Didn't lloyd just release these features?
John Moehrke (May 18 2021 at 12:21):
Agile, MVP, Pivot.
John Moehrke (May 18 2021 at 12:21):
we are not using waterfall
Brett Marquard (May 18 2021 at 12:22):
I disagree that this implication is fact.
What does 'next/previous' mean then? Are you saying we aren't trying to drive a work flow?
Brett Marquard (May 18 2021 at 12:22):
Agile, MVP, Pivot.
This gives folks ability to add whatever they want?
John Moehrke (May 18 2021 at 12:22):
it walks down the table of contents
John Moehrke (May 18 2021 at 12:22):
so yes, it expects that if you care about order, you will order your pages in that order
Brett Marquard (May 18 2021 at 12:22):
So I strongly think Previous/next should be optional
Brett Marquard (May 18 2021 at 12:23):
Walking down 'Table Of Contents'...no comment.
John Moehrke (May 18 2021 at 12:24):
I am not against optional. but I would say it should be default, and it should be the same when it is needed
John Moehrke (May 18 2021 at 12:24):
yes, walking down table of contents... including each artifact, and page of artifact
Brett Marquard (May 18 2021 at 12:24):
I definitely agree, should be the same when needed.
John Moehrke (May 18 2021 at 12:24):
which.. I would rather it not progress into artifacts
Brett Marquard (May 18 2021 at 12:25):
@Lloyd McKenzie Can you make optional?
John Moehrke (May 18 2021 at 12:25):
this however is also a step into the ability to produce a comprehensive PDF.. which many readers have indicated is necessary, and required by some regulatory bodies.
Brett Marquard (May 18 2021 at 12:25):
got-it, I hadn't heard that requirement before.
John Moehrke (May 18 2021 at 12:29):
them regulatory bodies are a pain.
Sarah Gaunt (May 18 2021 at 12:48):
Shouldn't we be talking about this in IG Creation - not here? I missed all the previous discussion on this because I don't really follow the committers stream...
Eric Haas (May 18 2021 at 13:41):
agree with @Brett Marquard the logical layout of the top bar menu and not some table of content drives a lot of the IGs. This is a website not a book and should not be forced into reading like one. These new template styling can be in my mind cumbersome and intrusive. The only reason for a next button is if it ties to the web site menu with visual cues. One should not have to discover hidden pages via this mechanisms. I am chagrined when I have to make comments regarding basic navigation on ballot comments to make a guide more readable. I would strongly urge that this be an optional feature and further that we focus instead on a style guide instead of providing new features to be abused. the pdf requirement is a canard IMO and should not be the only driver.
Eric Haas (May 18 2021 at 13:44):
If indeed we need to produce pdfs then let create pdf instead. Would save us a lot of time and effort chasing down minutiae when publishing IGs
Vassil Peytchev (May 18 2021 at 14:14):
FWIW, template issues are on github
Brett Marquard (May 18 2021 at 14:19):
Thanks @Vassil Peytchev ! Do you know if/where these are prioritized? Maybe it's as folks have time...
Lloyd McKenzie (May 18 2021 at 14:19):
I strongly agree that no IG should be designed to be read like a book. If the only/preferred way to navigate your IG is with next/previous, the design of your IG is broken. (And there a number of published HL7 IGs I consider to currently be broken by that criteria.) That said, every IG must have a table of contents and that table of contents is linear. And there are some people who do want to read IGs linearly. Sometimes that's just how they think, sometimes they want to ensure they don't miss anything, sometimes they're doing a formal review and page-by-page is the simplest way to manage it.
I don't think we should have this be optional. Either we decide it's a useful feature and all HL7 IGs have it, or we decide it's undesirable and none do. It shouldn't be a design decision because, as I said, no IGs should be designed with next/prev as a primary navigation feature. It's intended to be an unobtrusive navigation tool for those readers and those uses of the IG where it's helpful. Having some IGs that provide it and others that don't simply confuses readers. (We had negative ballots for the non-Trifolia generated Da Vinci IGs that didn't have this feature - and the Trifolia generated next/previous was more obtrusive and less complete in its navigation.)
Lloyd McKenzie (May 18 2021 at 14:20):
Happy for us to figure out a formal process for approval of template enhancements, though with respect to this one, we'll also have to deal with negative ballot comments asking for the feature.
Lloyd McKenzie (May 18 2021 at 14:24):
I'm not saying there can't be any variability between IGs, but that variability should only be driven by two things:
- agreed criteria that establish that the nature of the IG means it should be rendered differently (where we can explain those criteria to the community and they'll make sense)
- experimental features where someone is trying something out with the intention that it'll either be rolled out to all IGs in the future or rolled back if it doesn't work
HL7-published IGs should not have variation driven only by author preference (including mine)
Lloyd McKenzie (May 18 2021 at 14:25):
Ideas on how best to make decisions about template modifications?
Brett Marquard (May 18 2021 at 14:26):
I am wondering if we have matured enough that template modifications should be on a formal 'release cycle' with a WG overseeing/prioritizing features?
Brett Marquard (May 18 2021 at 14:27):
Do you have a reference to the negative vote
Brett Marquard (May 18 2021 at 14:29):
The ToC to me is an 'index' - I don't view it as a curated linear way to read a guide. Someone could use it that way -- but it would be a pretty choppy read in the IGs I have reviewed
Jose Costa Teixeira (May 18 2021 at 14:51):
unless I am missing yet another head of this hydra discussion, I would suggest we have a stream for IG templates where we can discuss changes, releases, processes, customizations....
Jose Costa Teixeira (May 18 2021 at 14:53):
About the process: there were some discussions to make the process a bit more formal/easy to follow. we should continue work on that.
Jose Costa Teixeira (May 18 2021 at 14:56):
@Brett Marquard the issues are mostly prioritized, it's a matter of value (perceived benefit vs effort vs dependencies).
Brett Marquard (May 18 2021 at 14:57):
I would love an outsider to drive usability requirements. Anyone on this chain (or in zulip) suggesting/adding features to help the 'new kid' is probably not the best judge. @Viet Nguyen as an FYI since I know he had an informatics student do a reivew across IGs recently
Jose Costa Teixeira (May 18 2021 at 14:59):
a more formal "release cycle" would be helpful (at least for me). We may also need to invest in documentation (e.g. the amount of work to document color configuration has surpassed the amount of effort implementing it)
Jose Costa Teixeira (May 18 2021 at 15:00):
@Brett Marquard finally something I can disagree / challenge you about in this thread (i was afraid i was only confirming your requests):
Lloyd McKenzie (May 18 2021 at 15:03):
I don't think we want a whole new work group. I think defining this as an official work group "project" with regular review calls and an announced list of proposals we're looking at would be fine. There's some challenges in this space in that simply agreeing "we should do that" can be a very long way from it being done soon (or done ever). For example, I expect we'd all be in favor of the IG publisher fully supporting translations - and we've even had meetings discussing how that might happen. But the odds of it actually happening without someone stepping forward with resources to drive the change is slim.
Grahame Grieve (May 18 2021 at 15:04):
FMG has as task to create a publishing council that has this authority, and that includes representation from IHE as well as some key HL7 players
Lloyd McKenzie (May 18 2021 at 15:05):
Agree that navigating by ToC is choppy. But, as a formal standard, all of our IGs must have a single linear organization that ensures that a reader has reviewed every part of the content. It's not the same as pointing to the Microsoft or IBM website where there'd be no hope of a table of contents (or of anyone ever being expected to "read the whole site".
Brett Marquard (May 18 2021 at 15:06):
Is there a single linear organization to http://hl7.org/fhir/?
Grahame Grieve (May 18 2021 at 15:07):
Grahame Grieve (May 18 2021 at 15:07):
note that you didn't ask whether there's a very useful one
Brett Marquard (May 18 2021 at 15:07):
I wonder how many clicks it would be with a next button :)
Brett Marquard (May 18 2021 at 15:08):
sorry, this is hard stuff and I don't want anyone to think I am not saying you aren't doing an incredible job.
Brett Marquard (May 18 2021 at 15:09):
Usability is hard, and everything is getting so big it's hard.
Lloyd McKenzie (May 18 2021 at 15:15):
The core spec is approaching a size where a complete review is pretty much impossible, though on the other hand, implementers aren't usually asked to conform to the core spec directly, so it's ok to not read it all. On the other hand, being asked to conform to an IG is a pretty common thing (that's sort of what they're for), so being able to review the 'whole' thing matters. And IGs should have a logical order of presentation where first there's context, background and supporting information, then formal expectations and then technical artifacts, ideally also organized in some sort of logical order.
Lloyd McKenzie (May 18 2021 at 15:16):
@Grahame Grieve - I don't recall a discussion about a publishing council at FMG? When was that brought up?
Grahame Grieve (May 18 2021 at 15:21):
it was a while ago.
Grahame Grieve (May 18 2021 at 15:21):
like 6 months or more
Jose Costa Teixeira (May 18 2021 at 16:13):
Brett Marquard said:
I would love an outsider to drive usability requirements.
Sorry, missed this thread - I think it's good to look at this with fresh eyes, but we do want feasible requirements. which does require a bit of immersion.
Jose Costa Teixeira (May 18 2021 at 16:14):
and some of these requirements seem like "we need faster horses" - personally I look at the previous/next links and think this is one of those.
Lloyd McKenzie (May 18 2021 at 16:25):
Even if we end up with a cross-organization publishing group, I expect we'll want an HL7-centric group that sets expectations for HL7 IGs - given that rendering expectations are quite different for IHE and may be similarly different for other organizations.
John Moehrke (May 18 2021 at 16:26):
agreed. although I am striving to keep IHE as close as is reasonable. (but, really... sometimes HL7 is silly.. :-)
Grahame Grieve (May 18 2021 at 16:27):
that would be FMG still.
Grahame Grieve (May 18 2021 at 16:27):
sometimes HL7 is silly.
but that's ok, because sometimes {X} is silly
Where {X} is IHE, but also any other organization.
Grahame Grieve (May 18 2021 at 16:28):
not only including the ones @John Moehrke works with :grinning_face_with_smiling_eyes:
John Moehrke (May 18 2021 at 16:29):
amen
Lloyd McKenzie (May 18 2021 at 17:08):
@Brett Marquard I don't understand why a desire for a more formal process means we need to roll back all changes. Changes are made to the publisher and to the templates on a semi-continuous basis. I think the only controversial change in my list is the roll-out of next/prev so that it's available everywhere. Frankly, I don't understand why that's controversial. I kept it as unobtrusive as I could. (Ideas for making it even less obtrusive would be welcome.) It's something some part of our community wants and there are legitimate reasons to want to navigate that way. Why would we say "No, we won't let you navigate this IG that way"?
Brett Marquard (May 18 2021 at 17:09):
I am not saying you can't make the option available, just not mandate all IGs include without further vetting
Jose Costa Teixeira (May 18 2021 at 17:09):
Why would we ever roll back changes?
Jose Costa Teixeira (May 18 2021 at 17:12):
the prev/next are on the footer/header. They don't bother me (and next to Lloyd I think I have suffered the most with them).
Jose Costa Teixeira (May 18 2021 at 17:13):
if we decide on a more formal process it should apply moving forward. including possibly deprecating features, once the requirements for that are clearer.
Jose Costa Teixeira (May 18 2021 at 17:13):
but not going back and holding back on features
Brett Marquard (May 18 2021 at 17:14):
Automatically enabling features that aren't vetted doesn't seem correct
Lloyd McKenzie (May 18 2021 at 17:14):
It's how we've always worked. I'm not arguing against improving process, I'm questioning the need to roll things back.
Jose Costa Teixeira (May 18 2021 at 17:14):
they are vetted with the current process (which we need to improve).
Brett Marquard (May 18 2021 at 17:15):
can you add a way in the next release to not make these mandatory?
Brett Marquard (May 18 2021 at 17:15):
Sorry @Jose Costa Teixeira , where is the current process?
John Moehrke (May 18 2021 at 17:16):
the not manditory is already built... fix at a version of template.
Lloyd McKenzie (May 18 2021 at 17:16):
Can? Yes. Is that something that we want to have in place long term, absolutely not. My question is why we'd want to introduce it short-term.
John Moehrke (May 18 2021 at 17:16):
I am still very confused as to the harm that has been caused.
Brett Marquard (May 18 2021 at 17:17):
I can't migrate to a new template without adopting.
Jose Costa Teixeira (May 18 2021 at 17:17):
@Brett Marquard the process has been - people are welcome to contribute with issues, PRs even better.
Brett Marquard (May 18 2021 at 17:18):
'has been' = more HL7 lore
Brett Marquard (May 18 2021 at 17:19):
I am still very confused as to the harm that has been caused.
nothing immediate, just slinging changes without a process is NOT a process.
Jose Costa Teixeira (May 18 2021 at 17:19):
(right, which is what brought us here. Trust in the community, willingness to do the work and accept the progress)
Brett Marquard (May 18 2021 at 17:19):
I appreciate they are posted on github
Jose Costa Teixeira (May 18 2021 at 17:19):
One thing we definitely need as part of the improved process is to tell people how they can use previous versions of a template so that they don't get surprises.
Jose Costa Teixeira (May 18 2021 at 17:20):
While that is not in place, we have no buffer.
Brett Marquard (May 18 2021 at 17:20):
and mandatory' features' should get some extra review
Grahame Grieve (May 18 2021 at 17:20):
there is a way to do that
Jose Costa Teixeira (May 18 2021 at 17:20):
@Grahame Grieve I know, my proposal is that perhaps we should document that.
Jose Costa Teixeira (May 18 2021 at 17:22):
I for one would appreciate help in documenting features. That is much more valuable than having a UXer explaining what the personas may want.
Grahame Grieve (May 18 2021 at 17:24):
well, you nominate the version of the template you depend on
Jose Costa Teixeira (May 18 2021 at 17:26):
we can work on that. I think it could be added as a github issue "document the way to use a fixed version of the template".
Lloyd McKenzie (May 18 2021 at 17:30):
The current process is 'anyone who wants a change submits an issue or complains on Zulip and someone else creates an issue. Those who have committer access make fixes and enhancements they think are reasonable and have time and energy to make'. That's the process that drives all of our tools at the moment (core publisher, validator, ig publisher, ig templates). I think there's limited appetite to over-constrain that process because right now we're seriously resource bound in getting tooling fixes and enhancements made and putting barriers in front of Grahame/Mark is that last thing we need. However, the call for broader review over changes that impact everyone is reasonable, and the desire to have a more formal process that helps define "what all HL7 IGs must do" is appropriate. That needs discussion & buy-in.
My suggestions are twofold:
- FHIR-I defines a formal project around increasing consistency of HL7 IGs and enhancing the usability of HL7 IGs. That project would have regular scheduled calls and would vote on changes the same as others. FMG and possibly MnM would co-sponsor
- We set up a stream on Zulip for discussion of proposed enhancements and perhaps even have a Zulip bot auto-post when a new issue gets raised (on either templates or publisher)
We should also have more regular migration of 'draft' templates into 'official' templates so that anyone who wants anything even vaguely new isn't forced to live on 'current' all the time.
Jose Costa Teixeira (May 18 2021 at 17:36):
agree. can we keep the issues in github at least for now? Or do they have to go to Jira?
Lloyd McKenzie (May 18 2021 at 17:37):
I wasn't proposing moving them from Git. Pretty sure we can have a bot that drives from Git as easily as Jira.
Brett Marquard (May 21 2021 at 18:12):
Thank you @Lloyd McKenzie for continuously stepping up to the plate to make things better. Draft Project to increase consistency & quality of FHIR implementation guides. I apologize for the snark here and in the other thread.
Lloyd McKenzie (May 21 2021 at 18:50):
Plan is to take that up with MnM, FHIR-I and FMG at the WGM. (International Council has also expressed an interest). FHIR-I discussion will likely be Wed Q1. After all three have had a chance to review (and hopefully endorse) we'll move it out of draft and start the official process.
Last updated: Apr 12 2022 at 19:14 UTC
