Stream: IG creation
Topic: Ballot publication processes going forward
Grahame Grieve (Aug 31 2018 at 21:14):
The ballot publication process was particularly messy and difficult this time round. The process is not scaling as well as it needs to. Some conclusions we've drawn from this cycle:
- we will have much clearer documentation around what is required for publishing an IG
- we will have much earlier deadlines around demonstrating that you can produce an IG
- we will have higher requirements around consistency in the IG itself
- we will have higher requirements around html rules and templates
- editors will have a form to fill out when they submit content to me for publication
- we will not be supporting delayed ballot opening
- we will be much more proactive in rejecting IGs going to ballot if they don't meet these requirements
Grahame Grieve (Aug 31 2018 at 21:14):
things will gradually become more specific over the next couple of months
Grahame Grieve (Aug 31 2018 at 22:55):
WIth this in mind, I'm making a change to the IGPublisher. From my next commit, when generating hl7.org IGs, the IG Publisher will check every single page it generates for the existence of 2 html features:
- a status bar insertion point
- a footer marker
Grahame Grieve (Aug 31 2018 at 22:56):
you will need to put these in your template, and manually in any other page that doesn't produce via the template.
Grahame Grieve (Aug 31 2018 at 22:57):
the status bar insertion point is a comment <!--status-bar-->, and it's where I insert the note about status that you can see here:
Grahame Grieve (Aug 31 2018 at 22:57):
http://hl7.org/fhir/uv/sdc/2018Sep/
Grahame Grieve (Aug 31 2018 at 22:58):
this gets updated as later guides are released
Grahame Grieve (Aug 31 2018 at 22:58):
the other thing that is required is a div with the attribute igtool="footer" - this marks the footer of the page.
Grahame Grieve (Aug 31 2018 at 22:59):
I'll gradually adding more additional checks on the html to force consistency along the rules documented here: http://wiki.hl7.org/index.php?title=FHIR_Implementation_Guide_Publishing_Requirements#HL7_HTML_Standards_considerations
Lloyd McKenzie (Aug 31 2018 at 23:09):
Do you want a comment for the status bar or do you want a mechanism where you can quickly and easily just plug in a blob for the status bar as part of the build? Because the latter is pretty easy and seems less clunky than doing a search and replace to me.
Lloyd McKenzie (Aug 31 2018 at 23:09):
It's my hope that once we've got the IG templating stuff working, we can just say that all IGs must use the same standard template.
Lloyd McKenzie (Aug 31 2018 at 23:10):
Also, what is your intent for the footer? That's not something you should override...
Grahame Grieve (Sep 01 2018 at 00:58):
in practice I do override the footer a lot - every single IG. I must at least fix links in there. Part of our work must be sorting out what should be in the footer. here's the candidate things that might be in the footer:
- ig version
- fhir version
- copyright statement
- search link
- history link
- home link
- toc Link
- diff comparison link
- license link
- qa page link
- IG generation information
- link to create an issue
Grahame Grieve (Sep 01 2018 at 00:59):
personally, I want to see:
- ig + fhir versions
- copyright statement
- diff link for ballots
- link to create an issue
- license link
Maybe:
- search / toc / history links
Grahame Grieve (Sep 01 2018 at 00:59):
I'd like to know why would we'd think that the footer differs between IGs
Grahame Grieve (Sep 01 2018 at 01:00):
as for the status bar: I need search and replace because I routinely do search and replace on already published guides to update the status bar when newer versions are published
Grahame Grieve (Sep 01 2018 at 01:01):
I do think that we should get to a single template, but some of the community will have to bend on the dearly held preferences if that's going to happen. Lloyd
Lloyd McKenzie (Sep 01 2018 at 01:33):
Well, the template used for SDC, CRD and genomics supports both markdown and HTML. What are the other points of contention?
I think that's too much info to have in the footer, but think it's totally reasonable to have a standard footer. In terms of search & replace, if that's what's needed later in the process, ok.
Grahame Grieve (Sep 01 2018 at 01:40):
well can we schdule some time to work on getting templating and an HL7 template nailed next week (not this week- I'll do the IG transform this week)
Brian Postlethwaite (Sep 01 2018 at 06:12):
The
At seems perfectly reasonable for a hl7 IG, but what about others?
Michel Rutten (Sep 01 2018 at 12:14):
I definitely see the need for enforcing requirements for IG ballot publication and CI build integration. Of course, I would like to ensure that Simplifier remains a viable alternative for authoring HL7 implementation guides. So I suggest that we try and keep official HL7 requirements on a procedural & functional level, as to allow the community/market to develop and use different alternative solutions.
Grahame Grieve (Sep 01 2018 at 20:20):
we''ll be making the requirements we need, whatever they are. We can discuss if you think they create problems for Simplifier. But after this last round... we're not going to accept anything but a well proven path
Eric Haas (Sep 04 2018 at 20:33):
@GG, I assume the history links go in the status box right?
Grahame Grieve (Sep 04 2018 at 22:07):
yes. but not only there, at the moment
Eric Haas (Sep 04 2018 at 22:27):
where else... its the only place in my igs?
Grahame Grieve (Sep 04 2018 at 23:00):
I've been putting it in the footer too
Eric Haas (Sep 04 2018 at 23:18):
? OK seems redundant to me since its so front and center in the yellow box at the top of each page. Is that official and should I update my footer template or wait?
Eric Haas (Sep 04 2018 at 23:32):
I'd like to template yellow box in - so its in the CI build too. Is their a problem with that approach?
Grahame Grieve (Sep 04 2018 at 23:47):
no there's no problem putting that in the CI build
Grahame Grieve (Sep 04 2018 at 23:47):
as long as it's contents are appropriate to being the CI build
Lloyd McKenzie (Sep 04 2018 at 23:52):
I'm open to that. We'll have to embed the comment markers to let Grahame do his search & replace - though I don't actually understand why a search and replace on that would be necessary...
Grahame Grieve (Sep 04 2018 at 23:54):
because the status changes retrospectively. Something that is the current version later changes so it's not the current version
Eric Haas (Sep 05 2018 at 00:04):
OK I have a bunch of liquid syntax to update it based on status and version. I'm going to put the publish box back in and keep the marker too just in case
Rob Hausam (Nov 02 2018 at 19:10):
(deleted)
Last updated: Apr 12 2022 at 19:14 UTC
