Stream: IG creation
Topic: next and previous
John Moehrke (Feb 18 2021 at 21:33):
I understand that there is aspirations of having automatic next and previous navigation in the IG publisher, but it is not there yet... SO, I figure I will hack it in the hard way into the bottom of my markdown files. Has anyone already done this, producing a nice way to show them, icons, or something? I would be happy to copy/paste rather than fuss over it myself.
Lloyd McKenzie (Feb 18 2021 at 21:40):
I've done the easy 2/3 of the work in the profiles. The tricky bit is making it work across pages in structure definitions, for example, when different IGs enable and disable different subsets of pages. That requires some Java work in the publisher to expose the relevant information. May get to it in March.
John Moehrke (Feb 18 2021 at 21:50):
I am okay leaving the SD alone. I am more just wanting to link my narrative pages
Lloyd McKenzie (Feb 18 2021 at 23:25):
You can do that manually now. But it'll be redundant once automatic support is rolled into the template.
Eric Haas (Feb 19 2021 at 22:08):
I don't want next and previous in the IGs I author and hope that it will be discussed before being imposed on the masses.
Eric Haas (Feb 19 2021 at 22:13):
The only time is useful is when you have a floating sidebar menu like this...
Lloyd McKenzie (Feb 19 2021 at 22:29):
We can discuss it, but I think the intention is that it'll be part of the base pattern and will show up everywhere. My intention is to make it unobtrusive though. There are a lot of people who want it. They like to page through the spec like it's a document. There are some places where that doesn't make a ton of sense, but in all IGs there are places where it does. What concerns do you have about it being introduced @Eric Haas?
Eric Haas (Feb 19 2021 at 23:34):
Having a poorly deployed new bells and whistles is worse than having none.
Jose Costa Teixeira (Feb 19 2021 at 23:54):
i don't see the IG as being a linear read, so the notion of "prev/next" sounds good for some pages but strange for others
Lloyd McKenzie (Feb 20 2021 at 00:11):
Every page in the IG exists in an ordered table of contents, so there is technically a next/prev for everything. It will typically be more 'useful' when looking at the narrative pages than when looking at artifacts, but some people like to page through everything, and next/prev gives them a more efficient way to do that than continuously navigating to the ToC.
I agree that "poorly deployed" is problematic, no matter the function. Are there any objections to a 'well-deployed' next/prev navigation mechanism? (And opinions on what 'well-deployed' means?)
Eric Haas (Feb 20 2021 at 00:43):
Format and design matter and in my opinion it is a weakness of our IGs as they try to emulate pdfs, word documents or books and poorly implemented navigation and things like the table of content ( vs site menus ) and section numbering conflate the 2. This degrades the quality of the user experience. The navigation should be clear enough from the menu and with IGs that have used nest and previous links in the past , it was the only way to expose pages that were otherwise hidden to the reader. (unless you slogged through the table of contents)
Lloyd McKenzie (Feb 20 2021 at 00:54):
I totally agree. If next/prev are necessary to reasonably navigate your IG, then you've messed up the design of your IG. (And we've published quite a few IGs where that's been a problem.)
However: There is a style of IG reading where next/previous is useful - both when reviewing and when consuming - where there's an objective of trying to consume either the whole thing or a particular topic area. And therefore, I think it's reasonable for the template to enable this.
I'd love your thoughts on any kind of automated metrics or detection mechanism we could use to identify IGs that are not navigable independent of next/prev. I'm not sure how we can detect it right now outside manual review.
John Moehrke (Feb 20 2021 at 16:41):
The interest for next/previous was not to emulate PDF. And this is why I think support on pages should be targeted. To just go down the table-of-content is not what I want. I have a few narrative pages that each build upon the other. So I really only need next/previous on these kind of pages. I do not want next / previous on most pages, specifically none of the technical pages. The technical pages hang together through specific text in their narrative. For this reason, i am okay with not having this automated. What I was looking for is some consistency to how each IG would present next/previous .
I ended up with simply using links
**[Previous](index.html) / [Next](2_actors_and_transactions.html)**
John Moehrke (Feb 20 2021 at 16:42):
bold made it stand out well enough for my Public Comment phase. Would love for something more standout for May.
John Moehrke (Feb 20 2021 at 16:45):
even if it was to just use icons like
:arrow_forward:
:arrow_backward:
Jose Costa Teixeira (Feb 20 2021 at 17:20):
Lloyd McKenzie said:
I'd love your thoughts on any kind of automated metrics or detection mechanism we could use to identify IGs that are not navigable independent of next/prev. I'm not sure how we can detect it right now outside manual review.
Can we link this to the discussion around structuring the content of an IG (evtl with Composition)? I think that for some IGs that have fixed, linear structure, we could enable this.
Lloyd McKenzie (Feb 20 2021 at 17:33):
All IGs have an intrinsic linear structure, because all IGs must have a table of contents that drives their section numbers. I don't see why we wouldn't have this supported everywhere. If someone wants to click 'next' when they're looking at a SearchParameter to see the next artifact in the spec (according to whatever organization scheme artifacts are arranged in the table of contents), that's a reasonable thing to support. I don't understand why we'd ever want to prohibit next/previous from appearing on a page so long as we ensure it's not visually disruptive.
Eric Haas (Feb 21 2021 at 04:29):
If we add in next and previous to the templates, I would like to see it implemented as I illustrated above.
Eric Haas (Feb 21 2021 at 04:29):
with the right floating menu
Lloyd McKenzie (Feb 21 2021 at 04:36):
I don't see next/previous in your floating right menu? I just see a mini-table of contents...
Eric Haas (Feb 21 2021 at 04:46):
Lloyd McKenzie (Feb 21 2021 at 05:09):
Sorry, I missed that earlier. That's actually much more obtrusive than what I'd envisioned. Do we need something that takes up that much space? Maybe the name of what's next and previous could be flyovers rather than shown on the screen?
I'd actually expected the links to just be at the top and bottom, but a floating bar is nice. How does it behave once you get down to the footer?
Jose Costa Teixeira (Feb 21 2021 at 09:22):
I'd like things like a floating bar to come from a jekyll theme.
Jose Costa Teixeira (Feb 21 2021 at 09:23):
I'd like to add theme support, so that we can do things like choosing the print-friendly of the web-friendly theme
Lloyd McKenzie (Feb 21 2021 at 14:00):
I think a 'print' theme is probably going to end up being a completely different template. Is there a reason why we'd want the floating bar to be configurable?
Jose Costa Teixeira (Feb 21 2021 at 18:55):
Lloyd McKenzie said:
I think a 'print' theme is probably going to end up being a completely different template.
Yes, I hope so. But there are some features in Jekyll themes that we could use, without reinventing.
Is there a reason why we'd want the floating bar to be configurable?
Within the same template - no.
In derived templates - I also don't see a reason
In completely different templates - maybe, but that becomes the template editor's problem. (meaning - I think we don't have to worry about it but shouldn't go out of our way to block it)
Lloyd McKenzie (Feb 21 2021 at 19:16):
Derived templates can always override and remove stuff. However, I'd like us to have a policy that for HL7-published IGs, such overrides aren't allowed. I.e. look and feel needs to be consistent across all the HL7 IGs. IGs published by other organizations can take our base templates and override to their hearts' content, or start from scratch designing their own.
Jose Costa Teixeira (Feb 21 2021 at 19:32):
that is what I mean with completely different templates. All of them are based on the base template, but outside of the HL7 stack of templates, the others are "different" - because they can do whatever they want.
Eric Haas (Feb 22 2021 at 16:56):
I used this example to show how I'd like the next and previous to tie into the a right sided floating menu. I am less concerned with the themes than this functionality.
Eric Haas (Feb 22 2021 at 16:58):
At this point I don't think changing the theme is useful as we have an established a look and feel for better or worse, but moving to a sidebar menu would be an incremental improvement and make the next/previous more intuitive
Eric Haas (Feb 22 2021 at 17:00):
and I just noticed the examples coarse language now... that was not intentional.....(did not even know that was a technical term...:-))
Lloyd McKenzie (Feb 22 2021 at 17:23):
Sidebar menu would be great - but need to make sure it will work for a wide variety of sizes of IGs - and that the sidebar retains proper context of where you are. If someone wants to work on that, that'd be awesome. (Also need to think about how it will work on mobile and smaller-screen devices.)
Eric Haas (Feb 22 2021 at 17:43):
There is probably a javascript+bootstrap solution. I have tried to implement in the past but no luck. Can HL7 just hire a frontend developer to make it so?
Lloyd McKenzie (Feb 22 2021 at 18:47):
Hiring a front end developer might be possible. However, if we're going to go that route, we should come up with a complete set of requirements, including mock-ups and varying edge-case IGs to test with so that the investment is efficient. We could then shop around to the various accelerators or others to sponsor/provide a grant. (HL7 might have a budget for limited stuff, but if we're going to hire a UX person, I'd prefer to do it once and do it 'right'.)
Last updated: Apr 12 2022 at 19:14 UTC
