HTML5, TOC levels, and topic heading appearance?

[Phlawm53]

My brain isn't working very well today. So my two-part question may just be silly. (Silly because I suspect may be overlooking some fundamental truth about how topics ought best to be presented in online help systems…)

ONE -
IF in a Flare HTML5 Target certain topics are nested below level one in the TOC, THEN is it even sensible to want to control the appearance of those nested topics' headings change based on their TOC level?

My objective is to provide a bit of explicit navigational information via a given topic's displayed heading. I know how to use Flare's Master Pages and breadcrumbs proxy, but I'm wondering if I can also communicate to the user "where they are" via the formatting (font-size, color, font-style, and so on) of a displayed topic's heading.

I'm thinking of how Flare print targets work in this regard. That is, IF if a print Target specifies Use TOC depth for heading levels, THEN Flare applies a given topic's header style based on where in the document (H1, H2, H3…) that topic appears. That feature enables one to apply a H1 to every topic's top-level heading, then let Flare sort out which CSS heading style is applied at the time the print target is generated.

I recognize that the HTML5 Target does NOT offer one the choice to Use TOC depth for heading levels. So I expect that there is no direct way to specify that a topic's TOC level be used to control how its heading will appear when displayed. I just want a quick sanity check that I'm not overlooking an "obvious" option or technique.

TWO -
IF there is in fact no direct way to specify that a topic's heading should vary depending on its level in the HTML5 project's TOC, then is there an indirect method to do it?

I'm wondering if, for example, JavaScript or similar "trickery" can be used to detect then apply a topic's heading "on the fly" depending on its level in the project's TOC. If yes, is that method so complicated, labour intensive, and inflexible that its benefit exceeds its overall costs?

Finally, is changing the appearance of headings based on project TOC levels even a sensible thing to want to do? Or am I simply missing the point of delivering topics-based content via an HTML5 system?

Cheers & thanks for your help and ideas,
Riley
SFO

[NorthEast]

I'm wondering if, for example, JavaScript or similar "trickery" can be used to detect then apply a topic's heading "on the fly" depending on its level in the project's TOC. If yes, is that method so complicated, labour intensive, and inflexible that its benefit exceeds its overall costs?

Put it this way, I think it's complicated enough that you probably won't get a solution from this forum, and would need to get a developer to look at it.

Of course, you could just manually change the heading levels in your topics; presumably that'd be ok for both print and help outputs.

Finally, is changing the appearance of headings based on project TOC levels even a sensible thing to want to do? Or am I simply missing the point of delivering topics-based content via an HTML5 system?

There wouldn't be a point in doing that with any of the projects I work with, but I can't comment on yours.

In a print/PDF output, using different heading level styles helps you pick them out when you scan through the document; so you can find the start of a new chapter, section, topic, etc. In a help system you're just looking at a single topic, so the initial heading level style isn't important for that purpose. In fact, if you click on different topics and the initial heading level is different, it'll probably just look a bit inconsistent.

If the reader does want to know "where am I", they can see that from the contents pane or breadcrumbs.

[i-tietz]

The root of that is almost philosophical, because it goes back to the difference between serial content and hypertext content.
As I stated every now and then before: I'm not a friend of mixing things up.

Hypertext content should be "self-sufficient", means: Each topic should give you a portion of information. That means you will have redundancies - Flare's answer to that is snippets, so at least you won't have to write the same content over and over again.
Serial documents are supposed to be read like a book. You start at the beginning and just go on reading page after page. On page 7 I can describe a function and the reader understands, because he already read about the necessary basics on page 3. I can rely on that and don't have to mention the same basics again.
Yes, in hypertext I could insert a link in those places and say something like "For details about this click here." But that loads another document and it's hard to not have the reader get "lost in hypertext".

Means for you:
If your content is rather like a serial document ripped into bits, then a styling telling me about it would be much appreciated (at least by me). But that would also mean that you have to offer a browsing mechanism that takes the reader to the "next page"or the "previous page".

[Phlawm53]

Thanks for your replies — they made me feel less embarrassed to have asked the question.

I'm not unhappy with the answers, either. As I said in my original post, I was worried that I was missing some obvious setting or technique. Now that I know I'm not, I can go on my merry way, such as it is…

Cheers & thanks 'gain,
Riley
SFO

[Nita Beck]

I am a firm believer in keeping things simple.

In my own practice, when developing a Help system, I only ever use H1 and H2 for topic headings. The H1 topics always and only ever serve as the opening topics for the major sections of the Help system, that is, they are linked to the first-level books of the TOC. All other topics' headings are set to H2. I don't believe that there is need to distinguish content further for users. Is the litte bit of semantic insight they might derive from different treatment worth all the authoring effort? And as Dave says above, if a user would like to know where in the overall structure of a Help system the topic in view resides, he or she need only look at the Contents and the breadcrumb.

Another advantage to using only H1 and H2 for topic headings is that they support what I call "content extensibility." The Flare author is free in future to quickly create a different target whose structure is not the same as the original target's structure but from the same collection of topics. Say I now want to create a user guide from the same Flare project, but that the print document's structure will not exactly match that of the Help system. Many (though not all) of the first-level books of the Help system may nicely equate to chapters in the user guide, so the H1 topics in the Help system become the opening topics in the chapters of the user guide. From the collection of H2 topics, I can build the outline for each chapter, without being forced to rigidly follow the exact same structure of levels in the Help's TOC. For the print target, I'll use the "TOC depth" option to have Flare manage the application of the appropriate heading styles, so that I don't have to.

Back to a Help system, the only time I've ever used the H3 style for topic headings is for a very large set of warnings. In addition to the H3 style, which rendered the headings in red, I also applied a page layout with a pale yellow background. In this situation, I did want users to instantly realize that they were in the Warnings section of the Help system.

[Phlawm53]

Nita:

Thanks for sharing your thoughts.

You and I have very similar approaches. I, too, stop and look at a deliverable's organization if, among other things, I find myself using a series of level-3 headings. And one of the reasons I find Flare so useful is that I can readily assemble bespoke combinations of output packages from a superset of "interchangeable parts" topics.

As I stated, my original inspiration for asking the question was two-fold. The first was to sanity check my observation that there was no direct way to configure HTML5 (or presumably WebHELP) Targets to use TOC depth to format headings as one can in Flare print targets. The second was to also sanity check my passing thought that being able to do that might in some way be useful.

Cheers & have a SUPER weekend,
Riley
SFO

[platkat]

As I stated, my original inspiration for asking the question was two-fold. The first was to sanity check my observation that there was no direct way to configure HTML5 (or presumably WebHELP) Targets to use TOC depth to format headings as one can in Flare print targets. The second was to also sanity check my passing thought that being able to do that might in some way be useful.

I'm actually trying to do this very thing, since I have to document a web interface that includes multiple pages with the same content. The interface has a tree control that displays these duplicated pages, and I have been instructed to mimic that for our in-product web help.

I can easily reuse pages in my TOC, but the breadcrumbs proxy for the HTML5 Target doesn't recognize each page as its own entity, nested under its own parent. The breadcrumbs display the topic as being under the same parent each time it is used.

For example, the TOC looks like this:

ParentPage1
CopiedSubPage
ParentPage2
CopiedSubPage
ParentPage3
CopiedSubPage

I want the breadcrumbs for the CopiedSubPage under ParentPage1 to read:
You are here: ParentPage1 > CopiedSubPage -- this is okay!

I want the breadcrumbs for the CopiedSubPage under ParentPage2 to read:
You are here: ParentPage2 > CopiedSubPage
But instead it reads:
You are here: ParentPage1 > CopiedSubPage -- this is a lie!

I want the breadcrumbs for the CopiedSubPage under ParentPage3 to read:
You are here: ParentPage3 > CopiedSubPage
But instead it reads:
You are here: ParentPage1 > CopiedSubPage -- this is a lie!

My un-elegant solution was to create a snippet of the content and make multiple pages so the breadcrumbs would display properly. I'll give everyone a moment to stop cringing...

TL;DR: Did you ask MadCap support about this and what was their answer?

Thanks!

[Phlawm53]

Platkat asked:

TL;DR: Did you ask MadCap support about this and what was their answer?

I didn't ask Madcap anything about contextually formatting online help system headings because the answers I received in this forum led me to conclude that I didn't have a problem.

The first part of my question was, does it make sense to change the appearance of topic heading levels in an online help system? The consensus was, no — doing that isn't generally considered to be a usability enhancement let alone necessity. I concluded that consensus opinion is correct.

The second part of my question was, did Flare 8 include an easily accessible feature to contextually format heading levels that I was overlooking? The answer was no: There is no straightforward way, let alone a Flare feature, that contextually formats help system headings. I'm not unhappy with that answer, either.

More to the point, my two-part question did not have anything to do with breadcrumbs. Breadcrumbs do, however, seem to be the focus of your question(?) So I might create a separate thread if there isn't already one that deals with breadcrumb behavior(?)

Cheers, thanks, & hope this helps,
Riley
SFO

[i-tietz]

My un-elegant solution was to create a snippet of the content and make multiple pages so the breadcrumbs would display properly. I'll give everyone a moment to stop cringing...

Unelegant? Then tell me: if I find the (one) topic via the index or the search - which breadcrumb should be displayed?
How is the topic supposed to know in what context it is opened?

To get the behaviour you want, there is only this one way. You should be thankful that you can use a snippet and don't have to edit all three topics separately.

[Nita Beck]

My un-elegant solution was to create a snippet of the content and make multiple pages so the breadcrumbs would display properly. I'll give everyone a moment to stop cringing...

Putting your content into a snippet that can then populate multiple topics is a best practice, so no one will cringe! This has been suggested many times on these forums. Here's one thread: http://forums.madcapsoftware.com/viewto ... &sk=t&sd=a