It is important that from any topic, the reader can find everything they need to know about that topic and related topics. Don’t assume they will use search features or contents to find other related topics – guide them there instead.
An easy way to do this in MadCap Flare is to use concept links and terms – they allow you to add a ‘see also’ list to a topic and the list will automatically contain links to related topics.
Concept Links and Concept Terms
There are two key steps to using concept links and terms:
Insert the concept terms in your topics. Think of these as labels that you add to your topics.
Insert the concept links to generate lists of links to topics. With the concept link, you insert a list into a topic and associate it with one or more concept terms. Then the list will automatically include links to any topics that have those concept terms.
Let’s say you have several topics about different aspects of an annual leave policy. It would be a good idea to have navigation links between these related topics, so you decide to use concept links. This will mean you can add a ‘see also’ concept link to the bottom of each topic and it will display links to all of the other annual leave policy topics.
In the diagram, the green markers represent Concept Terms and the blue marker represents a Concept Link, which has been added to a single topic (in this case, the Annual Leave Introduction topic).
You add a concept term to each of the topics. You use a concept term of ‘annual leave policy’.
In the image below, the green marker at the start of the heading is the concept term. We’ll look at how to add those later. At this stage, it is worth noting that Index markers also look like concept markers and it is important not to confuse the two. Index markers are shown in a lighter shade of green and if you hover the cursor over them, the pop-up shows ‘keywords’. If you hover the cursor over a concept term, the pop-up shows ‘terms’.
Then, in each topic, you add a concept link – the concept link is a list or pop-up that shows links to each topic that contain a particular term. In this case, you would set the concept link to show topics that contain the ‘annual leave policy’ term.
In the image below, the See Also is the concept link. Again, we will look at how to add these later.
When the project is built and published, the See Also list appears as a pop-up or a list, and it contains links to those topics that have the chosen concept. In the image below, it is shown as a pop-up list, which appears when you select the See Also link. But you can edit the stylesheet so that different text is used for the ‘See Also’ label. You can also set the list to appear as a regular list instead of a pop-up (regular lists are used for PDF output by default).
How to Add/Edit Concept Terms
You need to add concept terms before you can add concept links (you can’t link to nothing!). To add a concept term:
Open a topic to which you want to add a concept term.
Display the Concepts window (select View>Concepts Window).The Concepts window has two sides. The left-hand side is where you create/edit the concept terms. The right-hand side shows a list of all the concept terms currently in the project and if you expand a term, it shows you which topics contain that concept term.
To add a new concept term, enter the term in the field below Terms and press Enter. To add more concepts, just enter the new concepts in the field, one at a time (i.e. enter 1 term, press enter).If you want to remove a term, highlight its field and delete the text. The terms that are going to be added to the concept term marker are shown as a list on the left-hand side.
Go back to your topic and you will see a concept term marker has been added. If you want to change the concept terms for that marker, right-click on the marker and select Edit the Concept Association. Flare will display the Concept window and you can change the concept entries or remove them. However, you need to be aware that a topic can contain multiple concept markers, and the Concept window will only show the concepts for the currently selected marker.
When you first create a new concept term, it is not available until you save the topic. So save the topic now.
How to Add Concept Links
When you have added concept terms, you can add concept links to your topics. It is very easy to do in Flare:
Open the topic that is going to contain the concept link.
Position the cursor at the position where you want the concept link to appear. Typically, they appear at the bottom of topics or sections. You may want to add a paragraph break <p /> before the concept link to give it some space from the last paragraph.
Select Insert>Concept Link.The Concept Link option is on the far right of the Insert ribbon.
When you select the Concept Link option, the Insert Concept Link Control window is displayed.
The left-hand side shows all of the concepts that are in the project. The right-hand side shows the concepts that will be associated with the Concept Link that you add to the project. Use the left and right arrow buttons in the middle to move concepts from one side to the other as needed.
Select OK to add the Concept Link. It will only appear as the Concept Link marker in Flare – you won’t see the list or pop-up until the project is built.
By default, the concept links appear as pop-ups in HTML5 help and as lists in PDF. You can change the type of display used, and the appearance of the links by editing the MadCap |Concept and MadCap |ConceptLink set of properties in the stylesheet.
I am a freelance technical writer and I can help your business to deliver documentation that helps your customers and reduces your support costs.