When creating online help or user assistance, a common practice is to include a related topics link at the end of a given topic. The link usually appears as a clickable button labeled Related Topics or See Also. When a user clicks the button, a pop-up list of related topics appears, as shown below. Each topic is a clickable link.
In MadCap Flare, you can create this type of link using help controls. Flare offers three types of help control, and my favorite is the Concept Link. This control builds a dynamic list of topics that are associated by a concept. You first have to insert concept markers into the topics to create a concept association among them. This type of linking relationship is similar to A-links in other help tools.
Inserting a concept marker
Before you insert a Concept Link help control into a topic, you need to add a concept marker. To insert a concept marker, follow these steps:
- Open the topic.
- Open the Concept Window: View > Concept Window.
- Do either of the following:
- Add a new concept term by typing it in the entry field at the top; or
- Select a previously added concept term from the list in the lower half of the window. For each existing term, you can click the plus sign (+) to the left and view a list of topics that are associated with that term. You can also drag terms into the open topic to create new markers.
I usually place both concept and index markers at the very beginning of a topic, before the topic title.
Creating a pop-up concept link
Now that you have created concept associations among topics by adding markers, add a concept link to the end of each of those topics. This procedure creates the pop-up link that users see in your help output.
To create the pop-up concept link at the end of a topic, follow these steps:
- Open a topic that contains a concept marker.
- Select the following menu command:
Insert > Help Control > Concept Link (A-link). - Select a term on the right.
- Click the directional button in the middle of the window to copy the term to the left side of the window.
- Click OK.
Other types of help control
Flare offers two other types of help control. You’ll find both of them using this menu command: Insert > Help Control > [Type of Control].
Although I prefer concept links as a mechanism for topic association, I prefer the label Related Topics instead of the See Also label used in concept links. If you want to change the label for concept links, change the MadCap|conceptLink style extension. You’ll find the mc-label property under the Unclassified group.
Related Topics control
This control enables you to manually build a list of related topics by selecting files. The control appears as a button with the label Related Topics.
For more information, see these help topics:
Keyword Link control
This control builds a dynamic list of topics that are associated by an index keyword. You first have to insert index markers into the topics to create a keyword association among them. The default label for the control is Search Index.
For more information, see these help topics:
Another Option: Relationship Tables
When MadCap introduced DITA publishing capability in Flare 5, they cleverly integrated DITA relationship tables as yet another way to introduce related topic links. You can use this powerful feature in non-DITA projects. For more information, see About Relationship Tables.
Questions?
Help controls and relationship tables enable you to give users a simple way to find related information. They also enable users to learn by association. I encourage you to use these features when using MadCap flare to develop user assistance.
If you have questions or comments about these techniques, please add a comment or contact me.
{ 5 comments… read them below or add one }
I was just looking over this post today because I need to improve the search/findability aspects of the content in my webhelp. This was helpful — thanks.
Hi Tom,
Thanks for visiting! I’m glad you found this post helpful.
Eddie
I was investigating how Flare’s search algorithm works today, and I realized (with a little testing) that concept words are not factored into Flare’s search.
So if you add, for example, the word “zebra” as a concept to a topic, no results will be found in the search for the word zebra. But if you add “zebra” as an index keyword, especially inside the topic’s h1 tags, Flare does find that topic and usually pushes it high on the list of returns.
I’m not saying that inclusion or exclusion of concept words in search is good or bad, only that if search engine results are you goal, don’t count on any search returns from concept words in your topics.
One of my goals in exploring concepts and index keywords is to find a way to tag my topics in a way that works a bit like WordPress. I plan to post more on that later on my blog.
Tom, you are correct that concept terms are not included in search. I was advocating their use only as an automated mechanism for building Related Topics lists. Even though you mention in your other comment that their exclusion from search might be advantageous, I wish that MadCap would offer an option for including or excluding them. Authors who exclude an online index could then use concepts as search words in lieu of keyword markers.
Actually, Flare’s exclusion of concept words from the search may be advantageous, because you can then include certain tag words without worrying about cluttering up the search results. For example, you could add a concept word called “Recently Added Topics.” If a user searches for “add recent topics,” the search results won’t be ranking the “Recently Added Topics” concept phrase.
{ 2 trackbacks }