FHIR Chat · Base template suggestion(s) · IG creation

Stream: IG creation

Topic: Base template suggestion(s)

Sean McIlvenna (Sep 15 2020 at 16:53):

@Lloyd McKenzie and @Grahame Grieve
I'd like to suggest a few things for the template:

1. The table of contents should be more interactive. Users should not have to navigate away from their current page to access the table of contents. Would it be possible to have the "Table of Contents" menu be a pop-up menu (with a search field), rather than a completely separate page? For example: image.png
   
2. The table of contents's "Artifact Summary" should also include groups defined in the IG's resources (also shown in above "mock screenshot").
3. If groupings are defined in the IG's resources, then the Artifact Index should be split up into separate pages for each grouping. For larger IGs, the artifact index will be very large, and unwieldy.
4. The "Detailed Descriptions" should show the short field, as well as definition.

Sean McIlvenna (Sep 15 2020 at 16:56):

As a side-note, I think this changes will be especially important for publishing C-CDA using FHIR... C-CDA has 140+ profiles, and these will be important improvements for the navigability of the IG.

Lloyd McKenzie (Sep 15 2020 at 16:56):

1. I think that would be pretty hard - TOCs get rather long. However, you can create an issue requesting it.
2. The TOC reflects pages. Digging into pages would be challenging for HTML pages and nigh impossible for markdown pages. Don't want to treat different types of pages differently from a ToC perspective.
3. I'm not thrilled with that notion. I'd prefer a floating ToC that you could always see that lets you navigate the sections. Being able to search across the complete set of artifacts - and see the complete set of artifacts is helpful
4. The short field should be redundant with definition. Definition needs to stand alone - doesn't presume anyone has seen 'short'.

Sean McIlvenna (Sep 15 2020 at 16:57):

haha

Sean McIlvenna (Sep 15 2020 at 16:57):

Lloyd...

Sean McIlvenna (Sep 15 2020 at 16:57):

oye

Lloyd McKenzie (Sep 15 2020 at 16:57):

Note that most users don't use the ToC - and shouldn't have to. Navigation should happen between related pages.

Sean McIlvenna (Sep 15 2020 at 16:58):

there are navigation issues with larger implementation guides that needs to be addressed

Sean McIlvenna (Sep 15 2020 at 16:58):

these were my ideas on how

Lloyd McKenzie (Sep 15 2020 at 16:58):

My opinion isn't the final arbiter here - just giving my own reaction.

Sean McIlvenna (Sep 15 2020 at 16:58):

if you've got others, by all means

Sean McIlvenna (Sep 15 2020 at 17:00):

as for "create an issue requesting it"... I'm following @Grahame Grieve's guidance to create a thread here to start the discussion. he said this was the process for getting changes made to the tempalte

Lloyd McKenzie (Sep 15 2020 at 17:00):

If you've got 150+ profiles, not sure just moving 'profiles' to be a separate page is going to help much. This seems like a situation where 'search' could be relevant, though no clue how to make that happen.

David deRoode (Sep 15 2020 at 18:27):

Agreed that the general navigation experience through a FHIR IG could be improved so users/readers can see at a glance how the page they're looking at fits into the overall IG.

David deRoode (Sep 15 2020 at 18:44):

Groups allow for categorization use-case/domain artifacts within an IG; perfect for large IGs with hundreds of profiles, valuesets, and examples across multiple use cases. Categorizing by use case instead of conformance resource type could be perceived as more familiar/inviting to a wider domain/SME set of eyes (ie. beyond core FHIR reviewers). Or, I like your idea best: just embed searching

Grahame Grieve (Sep 15 2020 at 19:49):

All HL7 published IGs have searching now

Grahame Grieve (Sep 15 2020 at 19:50):

but you have to know what you might find in order to make search work for you. So it doesn't mean that navigation issues shouldn't be sorted out. And the CCDA IG is a good example of a lot of structurally similar profiles that need arbitrary grouping to make it easier to think about them. So we need to to think about Sean's issues

Lloyd McKenzie (Sep 15 2020 at 20:25):

Agree - wasn't dismissing the issues.

Vassil Peytchev (Sep 15 2020 at 20:41):

Note that most users don't use the ToC - and shouldn't have to. Navigation should happen between related pages.

In my experience, the ToC is the only way to understand what is in an IG, and in some cases seems to be the only way to navigate to certain parts of the IG.

Jose Costa Teixeira (Sep 15 2020 at 21:27):

I've been feeling the need to hierarchize the ToC a bit. And i'd like to have some different groupings instead of one flat Artifacts list.

Jose Costa Teixeira (Sep 15 2020 at 21:29):

My understanding is that everyone will want different groupings, so we cannot really hardcode a particular structure (by resource type etc). A few things are related: ToC, menu, IG groupings.

Jose Costa Teixeira (Sep 15 2020 at 21:31):

@Sean McIlvenna for search in the menu - do you mean something like this?
https://www.w3schools.com/howto/howto_js_filter_dropdown.asp

Jose Costa Teixeira (Sep 15 2020 at 21:36):

for the grouping - while I do feel a similar need, this would be a) good amount of work and b) potentially with implications in existing IGs

Sean McIlvenna (Sep 15 2020 at 21:44):

@Jose Costa Teixeira yes, that URL is an example of what I mean

Sean McIlvenna (Sep 15 2020 at 21:44):

"one flat artifacts list" is pretty useless in my opinion

Sean McIlvenna (Sep 15 2020 at 21:45):

I'm not even sure it's alphabetized

Sean McIlvenna (Sep 15 2020 at 21:45):

it doesn't say whether they are value sets, profiles, examples, etc.

Jose Costa Teixeira (Sep 15 2020 at 21:45):

Ok, i realized that this works for menus that have a lot of submenus, which is not the case for the ToC menu. I will ping if I see something that can be useful. But I do like the idea

Sean McIlvenna (Sep 15 2020 at 21:46):

:+1:

Sean McIlvenna (Sep 15 2020 at 21:46):

take a look at this IG: https://build.fhir.org/ig/HL7/cda-ccda-2.2/index.html

Jose Costa Teixeira (Sep 15 2020 at 21:46):

"flat artifacts list" - I mean it's still grouped, but as IGs get big, it's always hard to follow.

Sean McIlvenna (Sep 15 2020 at 21:47):

this is a work in progress... when done, there will be 2 to 3 times as many profiles

Sean McIlvenna (Sep 15 2020 at 21:47):

and when examples start getting added in, it will be even bigger

Sean McIlvenna (Sep 15 2020 at 21:47):

this IG needs some enhancements to navigability

Sean McIlvenna (Sep 15 2020 at 21:48):

so, if we're unwilling to change the template, then I could use some ideas on how to do improve this manually

Jose Costa Teixeira (Sep 15 2020 at 21:48):

Well, this artifact index shows someone has had a lot of work... but that's it. Too much information for a newcomer to make much out of it

Jose Costa Teixeira (Sep 15 2020 at 21:49):

I don't see unwillingness. We came here for an argument... :)

Sean McIlvenna (Sep 15 2020 at 21:50):

NP - when I hear "a lot of work", I suspect it won't end up getting done :P

Sean McIlvenna (Sep 15 2020 at 21:50):

not any time soon at least

Jose Costa Teixeira (Sep 15 2020 at 21:50):

(you'd be surprised...) :) - I am an apprentice but I can definitely appreciate the speed at which the wizards get things done.

Sean McIlvenna (Sep 15 2020 at 21:50):

I'd be happy to be surprised :)

Sean McIlvenna (Sep 15 2020 at 21:52):

anyways... I'd be open to suggestions on how I can do this myself for this one IG. However, I've heard similar issues with other FHIR IGs. so, I figured this was an opprotunity to improve all FHIR IGs. But, again, my chief concern immediately is for this IG

Jose Costa Teixeira (Sep 15 2020 at 21:55):

side topic: You seem to use markdown in the implementationguide.grouping.description - but it is a string

Sean McIlvenna (Sep 15 2020 at 22:02):

https://jira.hl7.org/browse/FHIR-28141
https://jira.hl7.org/browse/FHIR-28140

Sean McIlvenna (Sep 15 2020 at 22:03):

those were approved in FHIR-I, to change those fields to markdown, or at least treat them as markdown in the template

Sean McIlvenna (Sep 15 2020 at 22:03):

@Grahame Grieve thought the change would need to be to the FHIR IG Publisher to address those, and then later realized that the change would need to be the base template.

Sean McIlvenna (Sep 15 2020 at 22:03):

so, not really sure where we stand on getting those changes implemented

Grahame Grieve (Sep 15 2020 at 22:15):

I got confused by clicking on a wrong link somewhere. The template is where J#28140 is implemented. I've already done J#28141

Lloyd McKenzie (Sep 15 2020 at 22:15):

@Vassil Peytchev I agree that's true of some of our current IGs - I'm asserting that it shouldn't be. IGs should provide navigational guidance in the text and a menuing structure that makes it easy/intuitive to get to all content without having to wade through the table of contents. If you have to go to the table of contents, that suggests there's a problem with the menu and/or IG content. That said, I'm not opposed to making the ToC easier to navigate. It should, however, be predictable and tightly tied to the organization of the IG itself.

Jose Costa Teixeira (Sep 15 2020 at 22:17):

Yes. Sorry, i was not aware of the jira issues. @Lloyd McKenzie can I make a PR for J#28140? It's in artifactsummary.xslt, can we add a | markdownify }} there?

Lloyd McKenzie (Sep 15 2020 at 22:18):

y. Only question is whether it's safe to do that for R4 IGs.

Grahame Grieve (Sep 15 2020 at 22:19):

it should be. I do this routinely - process strings as markdown for older versions where they weren't

Lloyd McKenzie (Sep 15 2020 at 22:21):

I guess we can do it and see if anyone yells. If they do, we roll it back and make it version-specific

Sean McIlvenna (Sep 15 2020 at 22:21):

@Jose Costa Teixeira in your PR, can you also do the same | markdownify for https://jira.hl7.org/browse/FHIR-28141?

Jose Costa Teixeira (Sep 15 2020 at 22:23):

I think 28141 is java land

Jose Costa Teixeira (Sep 15 2020 at 22:23):

i.e. it's in the publisher, not template (i think)

Jose Costa Teixeira (Sep 15 2020 at 22:23):

i'll pick this up in a few hours

Sean McIlvenna (Sep 15 2020 at 22:24):

@Lloyd McKenzie

If you have to go to the table of contents, that suggests there's a problem with the menu and/or IG content.

I disagree with this. Why have a table of contents if it's not going to be used? Sometimes people know exactly what they're wanting to get at, and just need to quickly get at it without going through some sort of hierarchy of pages or other content that reference it. Table of contents has been around for a very long time because they serve a distinct purpose :)

Lloyd McKenzie (Sep 15 2020 at 22:28):

I'm not saying the ToC can't be used. I'm saying IGs shouldn't rely on it being used. Some people like navigating with the ToC and some people want to step through and tick off each item to make sure they've read everything. But a good IG should never rely on the ToC as the primary means of navigation (nor should it rely on prev/next links). When you go to read the Java spec (or most other technical specs), you don't generally worry about the ToC - in fact, I'm not sure if it even has one. And there's certainly no next/previous link. Instead, a combination of menus, panels and links within the body allow you to get wherever you need to go, with a fallback of 'search' if you're looking with something net new.

Sean McIlvenna (Sep 15 2020 at 22:33):

That makes sense. I don't want my IG users to rely on the ToC. But I'd like them to use it if they want, and for larger IGs, it's not very usable.

Lloyd McKenzie (Sep 15 2020 at 22:36):

One simple change would be to allow ToC sections to expand/collapse. We could also have a flag that drives whether we get a page per artifact topic or one for all artifacts (though I'd want the artifact topic pages auto-generated)

Sean McIlvenna (Sep 15 2020 at 23:07):

:+1:

Sean McIlvenna (Sep 15 2020 at 23:07):

I like both of those ideas

Sean McIlvenna (Sep 15 2020 at 23:07):

I'd really love to see a way to allow the user to access the ToC without navigating away from their current page. I think that would be really big.

Grahame Grieve (Sep 15 2020 at 23:09):

I don't like this idea. I think that there should be a page, which is the ToC, and it's frequently quite long, and it should not default to collapsed. But I think that it would be good for there to be a link that works the way Sean is describing

Sean McIlvenna (Sep 15 2020 at 23:14):

would it be a good idea to get a group of people on the phone to discuss these ideas? @Sarah Gaunt @Rick Geimer @David deRoode come to mind immediately... maybe more

Lloyd McKenzie (Sep 16 2020 at 02:05):

@Eric Haas and @Jose Costa Teixeira will also care - and likely help with the development

Lloyd McKenzie (Sep 16 2020 at 02:07):

I know of one set of FHIR IGs that have a collapsable ToC in a left-hand panel that automatically adjusts based on what page you're looking at. You can see it here: https://specs.prescribeit.ca/R2.0/erx/erx.html. Thoughts on that approach?

Grahame Grieve (Sep 16 2020 at 02:22):

I like it a little. What I don't like is how you open something up, looking for something. Then you try something else, and lose where you were

Lloyd McKenzie (Sep 16 2020 at 02:33):

How would you be any more lost than if you clicked on a link in the menu? The only way to get back to where you were is the 'back' button -which still works.

Grahame Grieve (Sep 16 2020 at 02:39):

I agree. Still, you're losing something, even if you didn't have it

Lloyd McKenzie (Sep 16 2020 at 02:54):

I'm a bit confused - how do you lose something you never had? Can you give an example of a website that would not lose what you feel we're losing here?

Grahame Grieve (Sep 16 2020 at 02:57):

I don't have an example. it collapses the menus when you navigate to a new page.

Lloyd McKenzie (Sep 16 2020 at 03:08):

It collapses the section you were in and expands the section you're in now. (At least that's what it's supposed to do. Would you prefer if it left open every section you'd been to?

Grahame Grieve (Sep 16 2020 at 03:20):

I'd prefer if it left open the ones you manually opened, yes

Lloyd McKenzie (Sep 16 2020 at 03:29):

The cost of that is more scrolling to get to another section

Grahame Grieve (Sep 16 2020 at 03:44):

actually it seems to inconsistently keep things you opened open

Lloyd McKenzie (Sep 16 2020 at 05:18):

Well, I guess we'll just ensure Eric writes better Javascript then... :)

Grahame Grieve (Sep 16 2020 at 05:18):

Awesome how Eric volunteered for that

Jose Costa Teixeira (Sep 16 2020 at 07:00):

Yes, thank you Eric. Now that we have a volunteer, one idea: would it make sense to have the menu like this?
https://codepen.io/ezanker/pen/vXYjXB

Jose Costa Teixeira (Sep 16 2020 at 07:01):

basically - TOC menu contains several items, but is collapsed. when you search inside the menu, it shows you the links that match.

Sean McIlvenna (Sep 17 2020 at 00:49):

All, would it be beneficial to have a group call about this? Should I send out a doodle poll for various slots over the next couple weeks?

Jose Costa Teixeira (Sep 17 2020 at 11:15):

I need help on how to markdownify this

    <p>
     <xsl:value-of select="f:description/@value"/>
    </p>

This , of course, doesn't work:

    <p>
     {{<xsl:value-of select="f:description/@value"/> | markdownify }}
    </p>

Jose Costa Teixeira (Sep 17 2020 at 11:15):

using %raw% also doesn't work.

Jose Costa Teixeira (Sep 17 2020 at 11:15):

@Eric Haas @Lloyd McKenzie ?

Lloyd McKenzie (Sep 17 2020 at 14:03):

You need to put the value of into a liquid variable, then markdownify that.

Jose Costa Teixeira (Sep 17 2020 at 15:19):

https://github.com/HL7/ig-template-base/pull/125

Jose Costa Teixeira (Sep 17 2020 at 21:01):

@Sean McIlvenna J#28140, when implemented, will be supported by the template

Sean McIlvenna (Sep 17 2020 at 21:33):

thanks @Jose Costa Teixeira

Jean Duteau (Jan 04 2021 at 22:24):

sorry to resurrect this thread, but I want to have more structure on my Artifacts Summary page (that is auto-generated by the publisher/template) and I'm wondering if adding groups in the IG will get reflected on this page? I may want to add groups anyways, but I want to know if there is something special that I could do to get better groupings on the auto-generated summary page or if I need to make my own summary page.

Lloyd McKenzie (Jan 04 2021 at 22:27):

The summary page will reflect whatever groupings you define. (We're having some discussions about the possibility of using Composition to replace groupings in R5 to allow deeper/more complex hierarchies.)

Eric Haas (Jan 04 2021 at 23:57):

I would too would like to rewrite the artifacts summary or allow other options and I don't think is an issue with grouping as much as presentation.

Lloyd McKenzie (Jan 05 2021 at 00:14):

We can look at changing how the artifacts summary is generated, but it should not be something that varies from IG to IG - especially in the HL7 publication space. We want the behavior and appearance to be consistent across all of the IGs.

Jean Duteau (Jan 05 2021 at 01:40):

why does that need to be consistent? if I've got a small guide, my needs are quite different from a guide with a huge number of artifacts

Lloyd McKenzie (Jan 05 2021 at 02:30):

The mechanism that generates it needs to be consistent so that all small guides work the same and all big guides work the same and the look and feel is consistent from small to large. I'm not saying that the mechanism can't allow for a navigational approach that scales well across small and large guides, nor am I saying that what we have now does that. Just that we don't want each author coming up with their own approach.

Lloyd McKenzie (Jan 05 2021 at 02:31):

Consistency matters most for ease of use by implementers. We don't want there to be a learning curve moving from one IG to another. (Though ease of maintenance is another consideration. Someone who knows how to maintain one IG should be able to maintain any other HL7 IG without having to learn a completely different approach.)

Last updated: Apr 12 2022 at 19:14 UTC