Stream: ig publishing requirements
Topic: Adding artifactId to artifact summary
Ramandeep Dhanoa (Sep 10 2021 at 17:19):
ig-template-base change: Change the artifacts rendering to be a table with 3 columns with the heading "Title, Artifact Id, Description" where title and description correspond to what's there now and Artifact Id will be the extension id (or profile id or value set id, etc.) I.e. we'll do this for all artifact types.
https://jira.hl7.org/browse/FHIR-20776
https://github.com/HL7/ig-template-base/issues/175
OldView.png
NewView.png
Grahame Grieve (Sep 13 2021 at 12:05):
why would we want artifact id?
Lloyd McKenzie (Sep 13 2021 at 14:04):
For the same reason we want it in core - so you know what you can refer to.
Grahame Grieve (Sep 13 2021 at 17:20):
it occupies a lot of space, and you probably need the whole canonical, which you can get. Why do you need it to occupy space in the table? It seems like a bad waste of space to me
Lloyd McKenzie (Sep 13 2021 at 18:49):
Not all of the resources will have canonicals. It's a ballot issue for one of the IGs asking for it. We could possibly use a copy button and a flyover if real estate is that big an issue.
Grahame Grieve (Sep 13 2021 at 19:04):
well, IGs should be able to rule ballot issues like that out of scope. I do think that it's a low value use of reading space, but I'm interested to hear why it's important
Lloyd McKenzie (Sep 13 2021 at 21:23):
The specific issue is that title names of value sets, code systems, etc. can differ (sometimes quite a bit) from their formal ids. So if you know what you're looking for in an IG, the title names aren't that helpful.
Lloyd McKenzie (Sep 13 2021 at 21:26):
If the IG isn't yet published, the canonical URLs won't resolve
Grahame Grieve (Sep 14 2021 at 01:10):
I'm not understanding... the canonical will be presented. How are you going to access them?
Lloyd McKenzie (Sep 14 2021 at 04:14):
Right now, we show title and description on the artifacts page. So if you go to the artifacts page looking to see information about a particular extension (or any other artifact) you have a canonical for, you have to guess what link to click on. If we expose the id of the resource, then it's super clear.
Eric Haas (Sep 14 2021 at 05:14):
I am not a fan of this exposure of a highly technical artifact this way. It degrades the readers experience. IMO, if you want the id click on the resources. (BTW @Ramandeep Dhanoa you hijacked this thread, next time create a new topic)
Elliot Silver (Sep 14 2021 at 05:18):
Maybe the problem being being solved is, "I know the canonical, how do I find the resource"?
Grahame Grieve (Sep 14 2021 at 06:11):
well, how do you find it? where? In the package? Find it by the canonical...
Elliot Silver (Sep 14 2021 at 06:25):
I meant, "I know the canonical, now where do I find that profile, etc. in the IG" This could be useful if I want to read the narrative around it, see examples, etc.
Grahame Grieve (Sep 14 2021 at 07:28):
well, I kind of follow, but this way you need to find the link to it, so that you know where to find the link to it.
Ramandeep Dhanoa (Sep 14 2021 at 17:03):
Thanks everyone for your input. From IG Authors/Editors perspective it is relatively easier with the 'Artifact Id' - to find the profile (or extension, etc.) in the IG folder (sometimes 'Title' is quite different from their artifact id, and you have to click on different items to see which one you are looking for) . But, I also agree that this may affect end users' readability experience.
@Eric Haas My apologies, I will ensure that in the future (sort of newbie here in terms of IG template change process)
Grahame Grieve (Sep 14 2021 at 17:07):
so this is an authoring concern?
Grahame Grieve (Sep 14 2021 at 17:07):
I think we assumed that authors can just look at the links to see, and then can choose how to do file naming
Ramandeep Dhanoa (Sep 14 2021 at 17:27):
Originally, it's an SDC IG ballot issue (reported here https://jira.hl7.org/browse/FHIR-20776
" It would be really helpful if the names of extensions in 12.0.3 were included in the list (perhaps in the description). The user-friendly titles ("Context resources") are nice, but it if you are searching based on the extension name ("sdc-questionnaire-launchContext") it can be difficult to find.)
Grahame Grieve (Sep 14 2021 at 17:30):
so it's actually about canonical URL then?
Lloyd McKenzie (Sep 14 2021 at 19:32):
I moved the thread to its own topic. If you see an artifact being referenced (by canonical or by id) and you want to check it out, it's not necessarily the case that the canonical will resolve or that there'll be a way to navigate directly to the artifact. What you want to be able to do is go to the artifacts page, hit "Ctrl-S", type part of the id and get there. Given that this is a "table of artifacts", I don't think that the formal id of the artifact is 'noisy'. We expose it in the core spec, for example in our lists of examples. If it's not a waste of space/noisy there, why would it be considered so in an IG?
Lloyd McKenzie (Sep 14 2021 at 19:33):
Right. You're searching by the tail of the canonical. You could also have the id of an example (perhaps referenced by a different example) and be looking for that.
Grahame Grieve (Sep 14 2021 at 20:02):
the id? or the canonical?
Lloyd McKenzie (Sep 14 2021 at 20:55):
Strictly, all that's needed is the tail of the canonical. The base is the same for everything in the IG, so displaying the full canonical all the time is indeed a waste of space (and ugly). Though perhaps having a 'copy' button that grabs the full URL or even a versioned canonical would be a nice addition - this in cases where you're scanning the artifact list for an extension you know is there and then find it and want to save from clicking through to grab the canonical. That's not as critical a use-case though.
Grahame Grieve (Sep 14 2021 at 21:03):
The base is the same for everything in the IG
except when it's not
Grahame Grieve (Sep 14 2021 at 21:04):
but if it's really hard to find an artifact, we should have an index-by-canonical page
Lloyd McKenzie (Sep 14 2021 at 21:10):
Creating "yet another index page" to me seems a log uglier and less convenient than just sticking the id in the table. I guess if your canonical root isn't your IG root, we could have the code display the full URL, but that should be a super-rare exception.
You haven't yet answered the question why is it ok to display the ids in the core spec if it's not ok to do it in IGs?
Grahame Grieve (Sep 15 2021 at 02:25):
where we do it? the examples? because people refer to the examples by their id
Lloyd McKenzie (Sep 15 2021 at 04:25):
And people refer to extensions and profiles by their ids too - at least those who work with them in other profiles or instances.
Last updated: Apr 12 2022 at 19:14 UTC
