Monday, March 11, 2019

A Comment About My MadCap Flare Links Webinar

I gave a webinar on Flare link types for MadCap on Thursday, March 7, and got the comment below from Jane Brewster, Information Architect for the White Clarke Group in the UK. I appreciate comments like this because my theory is that there's always someone out there who's tried something that I have not and the best thing to do is to learn from them.

With that, here's Jane's comment:

I thought you might like to know another pro for using togglers rather than hotspots, particularly applicable if you single-source for HTML5 and PDF. I initially used dropdowns but was very pleased to discover togglers and how flexible they allowed me to be with formatting.

In the PDF target I want our toggler or dropdown hotspot to be a sub-heading that sits correctly within the hierarchy, so it might be h2, h3 or h4 depending on where the topic sits in the TOC hierarchy. 

However dropdowns don’t allow the hotspot to dynamically change style if the topic sits at a different level in the output – the style is static (unless I’ve missed something obvious of course!).

To get around this use a toggler link conditioned for the HTML5 target followed by a heading conditioned for the pdf target (usually h2 as our topics all have h1 as the main heading). That way in the PDF if the topic is at the top level the toggler heading is H2, but if the topic is at the next level down the toggler heading is automatically h3, and so on.

Moving on to XRefs, I agree with not listing them all at the beginning or end of the topic. However I like to use them slightly differently to the way you describe. Having worked previously with online and PDF help that had to be AAA compliant (so suitable for any differently abled user, possibly using a screen reader), I’m aware that just putting a link in the middle of a sentence isn’t always appropriate (particularly for screenreaders), so I put them at the end as a more explicitly worded reference.

For example, instead of:
I really like using Madcap Flare because it’s a very flexible authoring tool.

I use:
I really like using Madcap Flare because it’s a very flexible authoring tool, see  Madcap Flare.

The PDF output is in the format:
I really like using Madcap Flare because it’s a very flexible authoring tool, see Madcap Flare (on page 3).

I’ve used hyperlinks in this example but they would be XRefs in Flare. This phrasing also gets around the problems caused when you want to use an XRef to a topic with a title that doesn’t make sense in the context of the sentence you’re linking from (not a problem with hyperlinks of course!) so you can be a bit more flexible with topic titles.