Issue with TopNav when you include topics >1x

[doc_guy]

Our team discovered an issue with TopNav output that affects all versions of Flare that create TopNav output. This occurs when a topic appears in more than one location in the TOC.

From what I can tell, when Flare compiles a topic for output, it only processes each topic one time, regardless of how many times that topic appears in the output. This is problematic for a couple of reasons.

First, consider the sidebar that shows where the topic fits in its current context. The sidebar is generated only once... the first time Flare finds the topic in the TOC. Well, if a topic is only in the project in one location, that's great. The sidebar is correct. However, when the topic is in the TOC a second (or subsequent time), Flare just references that topic that was previously built. This means that the sidebar is no longer correct; the sidebar shows the context of the topic the first time it was found in the TOC. The sidebar never shows the context of the topic in those subsequent locations in the TOC.

Additionally, this is trouble for the breadcrumbs, which also show the position of the topic in the the first instance, not the position of the topic in the second instance.

We have customers who are frustrated with the documentation because they are trying to follow a flow of information from topic to topic, but in the middle of that, they are suddenly in a completely different location in the project.

One solution would be to create new topics and use the common content in snippets so each instance of the content will have a separate file name. If the number of topics were small, that would be okay, but in our case we're talking potentially a hundred topics or more. We build smaller versions of our content into some targets, and then we have a master help system that contains all the smaller help systems grouped into a single help system. In the smaller help systems we have no problems, but when we combine them into a large comprehensive help system, we get into trouble.

I'm logging this as a bug in Flare. If you've seen this problem, or you think it is something that MadCap should address, I invite you to log it as well.

[Nita Beck]

Paul, I don't think this is specific to Top Nav. It's true as well for HTML5 tripane and probably other online targets, too.

The issue of the "broken breadcrumbs" and "TOC sync not working when a topic appears in several places" have been discussed for years on the forums. (I'm not picking on you... )

The best practice that has been promoted here on the forums for years is the very snippet solution you've mentioned. (I think it was LTinker68 who's the champion of the solution.) Put the guts in a snippet and then have one topic for each instance that you need that content to appear on a TOC, with each topic having in it only its own heading and the snippet. An additional best practice is to exclude from search all but the topic that appears first on the TOC, so that users don't get confused / annoyed when doing a search and having multiple hits that look like duplicates ('cause, well, they *are* duplicates). And maybe also index only the first topic.

I'm not sure how much headway you'll get convincing MadCap that this is a bug. That said, you've got a great reputation with MadCap, so go at 'em!

[doc_guy]

It is worse with top nav, I think because it destroys navigation.

[Nita Beck]

It is worse with top nav, I think because it destroys navigation.

I completely agree.

Going off on a tangent, I've taken to including a "sitemap" topic that lists the entire set of topics in a Top Nav system, as a series of links, nested to show hierarchy. I'm not the inventor of that solution; Dave Lee is. You might find that your users would find a "sitemap" useful, too.

I'll see if I can look up the forum post in which Dave talks about his solution. Found it: viewtopic.php?f=12&t=26904&p=118584

[NorthEast]

Yep, as Nita says this is an age-old issue; it was always a problem if you used breadcrumbs or the mini-TOC, and you'll see it now in top nav and the menu proxy.

Mind, I don't really see how MadCap can fix this either. For example, say I arrive at a topic from the search, or by following a link from another topic. If that topic is copied in several places in the TOC, then which one of those several locations should be displayed?

So if you think about it, having the same topic in several places (in web outputs) is always going to break any form of navigation. And it'll still break whether the navigation links are built-in to the page (like it is now), or whether the navigation could be generated dynamically at run-time. So I can't really see a feasible solution to this - how would you expect it to work?

You can use the snippet method to create multiple copies of the topic, although I'd be looking at why I have these identical topics in the first place. I tend to avoid having absolutely identical topics altogether, and only have copies of a topic if there are some slight contextual differences between them (i.e. the topics have some different content, using using snippet conditions).

One slight difference with menu proxies (to other navigation) is that you can multiple menu proxies, and link each menu proxy to a specific TOC file. This means you can have a topic that's in two different TOCs, and display both TOCs/menu proxies in that single topic. So that's ok, but having the same topics twice in the same TOC is still a big NO.

[RamonS]

When I read threads like this my mind stops at a different place. Yes, there are tricks to overcome it and I do understand that it is frustrating that the help system works as designed, but not as expected. In thinking about a solution I always came back to this issue:

One solution would be to create new topics and use the common content in snippets so each instance of the content will have a separate file name. If the number of topics were small, that would be okay, but in our case we're talking potentially a hundred topics or more.

If there is so much common (repetitive?) content I wonder if there are better approaches to structuring the entire help system. I do not know the content nor the context, but still wonder if there is a means to move all that common content into one section that is used by all outputs. I figure I mention it in case it is an alternative.

In general, when I come across such issues I spend not more than half a day tops in discussing and evaluating alternatives. After that it is typically faster to just stop what I should do and fix this issue. I spent many hours copying and pasting content, then restyling and refurbishing because that was the clearest path towards the goal. I am sure there are more clever solutions that might have shaved off hours of work, but figuring those out would have lasted longer than using caveman tech and n00b practice. Note: I do not see that as viable for recurring tasks unless the process is annoying but quick.
Even if it is hundreds of topics, it is a one time process to refactor those topics into snippets and inject snippetized topics where needed. Yea, it will rapidly inhale, but in the end it is still limited in scope and more importantly will make customers happier. I tell devs all the time that it is perfectly fine if we go through mindless grunt work so that the customer has a better experience.

OK, stepping down from my soap box now.

[doc_guy]

You can use the snippet method to create multiple copies of the topic, although I'd be looking at why I have these identical topics in the first place. I tend to avoid having absolutely identical topics altogether, and only have copies of a topic if there are some slight contextual differences between them (i.e. the topics have some different content, using using snippet conditions).

Let me give some background on the project to explain why we have done this.

In my new company, I've got topics included in the web output in multiple places because I have nested TOCs in my master TOC for web output. I'm trying to single source as much as possible. My company produces 12 PDFs, some as long as 1000+ pages. A lot of that content is common across two or more guides. For example, I have a guide that is for SDK users and a guide that is for Admin Console users. There are a lot of similar concepts for these two audiences. I have an "About Widget" topic that explains what our software does. It needs to be in both the Admin guide and the SDK guide. In my online TOC, I have a folder for each of the child guides that are in my project. Those folders have the child-guide TOCs nested, so any changes in the child guides are automatically updated in the online TOC without having to make the changes in two places.

My online users then get the same information flow experience regardless of if they are in the online version or in one of the PDF guides. (This is important to our customers who have for a long time relied on the PDF documents, and they have a tendency not to 'trust' the online help if the content is presented in a different order than is in the PDF guides that they love and cherish.)

With that background in mind, I hope you can see why, up to this point at least, we have topics that appear in multiple places in the same online output. Is it ideal? Hard to say. If I make a different TOC structure for my online output than I have for my PDF guides, I'm stuck with updating multiple TOCs, which for single-sourcing reasons I'd rather not do.

So if you think about it, having the same topic in several places (in web outputs) is always going to break any form of navigation. And it'll still break whether the navigation links are built-in to the page (like it is now), or whether the navigation could be generated dynamically at run-time. So I can't really see a feasible solution to this - how would you expect it to work?

That's true coming in from search. The user (or Flare's search, for that matter) will have no idea which context I'm looking for.

I'm still thinking this through, so I reserve the right to change my mind <grin>, but I think I wish Flare, at build time, would generate a version of the topic each time it is in the TOC, and insert the correct breadcrumbs, mini-TOC content, and sidebar TOC content for each instance of the topic in the content. So it would generate distinct copies of the file for each entry in a referenced TOC. Then, at least when people are browsing through the content sequentially, they will see all the topics in their correct context (breadcrumbs and menus). That part seems pretty simple. Yes, it duplicates content in the output, but that isn't a problem from a single-sourcing perspective.

Where it gets complex, like you (or somebody) said, is when you have the user locating the topic either through a search result or through a direct link (or cross reference). In the case of search, I would be fine if the topic shows up in the search results the number of times that the topic appears in the TOC. To me, that's logical, and even desired. If I open the topic and I see in the breadcrumbs that I'm in the wrong book/section/etc., then I don't know if this search result means it will work in the context I'm expecting. I can then go back to the search results, find the one that has the correct context, and now I KNOW that the search result is directly applicable in my situation.

As for the direct links/cross-reference scenario, I think, based on my previous wish of creating multiple versions of the file, that the build system would try to resolve the link as it would in the TOC where the file/link/cross-reference appears. If it can't find a match in that TOC, then it would look outside that TOC and link to the first time it finds the topics in the parent or sibling TOCs. This solution works for me, because I'm coming from the assumption that there is topic duplication in the output **because the topics are duplicated in child (nested) TOCs in the main TOC in the project.** I do recognize that this solution doesn't work if there are duplications of topics in the lowest-level nested TOC. (And I agree with Ramons' point about removing duplication in a single, child TOC. My problem is that my TOCs exist as separate deliverables, and when you combine them together to create a single master web output I get into trouble.)

One slight difference with menu proxies (to other navigation) is that you can multiple menu proxies, and link each menu proxy to a specific TOC file. This means you can have a topic that's in two different TOCs, and display both TOCs/menu proxies in that single topic. So that's ok, but having the same topics twice in the same TOC is still a big NO.

Does this work if the TOCs are nested in a master web TOC like I've described? I can see how it would work if the TOCs were in their own targets, but I'm wondering if it applies when TOCs are combined by virtue of a parent/child TOC relationship, if that makes sense.

[doc_guy]

Even if it is hundreds of topics, it is a one time process to refactor those topics into snippets and inject snippetized topics where needed. Yea, it will rapidly inhale, but in the end it is still limited in scope and more importantly will make customers happier. I tell devs all the time that it is perfectly fine if we go through mindless grunt work so that the customer has a better experience.

OK, stepping down from my soap box now.

Always glad for the soap box. I need people to challenge my basic assumption, because I make no claim that the basic assumptions are correct!

I agree that if refactoring is the right choice to make the project work better, then it is something we should do. For me (like you, apparently) the customer's experience is more important than me doing grunt work to make sure the customer has a good experience.

What bugs me in this case is that Flare won't let me treat any topic as a snippet. I can only insert actual snippets inline in a Flare topic. I don't love the idea of moving all this common content into snippet files because I think it makes that content harder to find. When you look at the source code of a snippet vs. a standard topic file, the code is the same (from what I can tell). The file extension is different, but Flare basically takes whatever is between the BODY tags and insert it into the topic calling the snippet. Why can't this work on other topics that don't have the snippet extension?

[LeslieT]

Hi Paul,

I have learned so much from you over the last few years, and it looks like I might have something that would be of help to you.

I have successfully used topic files as snippets. Where I am currently working, the customer service teams have these "knowledge articles" on a support site and what was needed what was really included in a small collection of topic files. Rather than having to "snippetize" all of the topics to accommodate that, I experimented and if you use the snippet block encoding but reference an HTML topic file using some of y=our topic template files. Turns out that it honors the reference just as it would a snippet. Here is what it looks like in the text editor:

Code: Select all

<body>
        <h1 class="ArticleTitle">Article Title</h1>
        <p>An article includes a small collection of topics, with "header" content that captures all of the information and fields required to populate and manage the article within SalesForce. This is a template for creating the Knowledge article header and embedding the referenced topics. </p>
        <p>The Header information is followed by a sequence of topic references (using a snippet block that points to an HTML topic file instead of a snippet). Insert or modify theses references in the Text Editor at the code level. </p>
        <MadCap:snippetBlock src="ConceptTopic.htm" />
        <MadCap:snippetBlock src="TaskTopic.htm" />
        <MadCap:snippetBlock src="ReferenceTopicTable.htm" />
    </body>

So I think you could embed a topic in a topic to create another version of that topic that does not break the navigation. I haven't experimented using it without an h element at the top, so hopefully if that is missing from the container topic it would use the one from the embedded topic as the heading in the output. Of course this does mean that there would be "duplicate" topics for a search, so that might be something else to consider.

I'm looking forward to hearing about how you solve your use case.

Cheers,

Leslie

[doc_guy]

Leslie,

That is awesome! Thank you! I'm going to check into that right now.

[doc_guy]

Leslie, you made my day! Thank you! I love it.

[LeslieT]

Paul,

So glad to have helped! Your info has helped me many times in the past and it is great to return the favor

Leslie

[NorthEast]

It may be possible, but is there any particular reason why you'd want to insert a topic as a snippet instead of an actual snippet?

I know it might save 20 seconds, but I actually find it quite useful to have a distinction between a topic and a snippet.
If I used topics as snippets, then it's not immediately obvious that the topic content is being reused as a snippet.

[NorthEast]

Does this work if the TOCs are nested in a master web TOC like I've described? I can see how it would work if the TOCs were in their own targets, but I'm wondering if it applies when TOCs are combined by virtue of a parent/child TOC relationship, if that makes sense.

Yes, when you insert the menu proxy, you can specify the particular TOC file - so it doesn't have to be the default (master) TOC set for the target.

So in your case, you might have a separate master page for each 'guide', and in each master page insert a menu proxy which is linked to that particular guide's TOC (instead of the master).
Then the topics in each guide would have their own individual menu, showing navigation only for that guide.

The top nav will be using the target's TOC (your master TOC), so its drop down menu will be use that TOC structure - which might just be links to each guide, but you can choose how many levels to include.

Of course, you still need to set up any duplicated topics as individual topics (using snippets), if you want them to appear as individual topics for each guide.