In my last post, I explained why FAQs are not the best means of helping users and site visitors find information. I suggested that you extract the key words from FAQs and transform them into topics. I introduced three common topic types: concept, task, and reference.

In this post, I will give tips and examples for writing each of the three topic types. My examples apply to a general business context and are somewhat simplified. If you are a technical writer, your topics will often be more complex.

Concept

Write a conceptual topic when you need to give an overview of a subject. To plan your content, ask yourself what readers need to know.

Suggestions for a Conceptual Topic

• Since a concept is descriptive, start the topic title with About.
• Introduce the concept and provide an explanation.
• Give an example to reinforce understanding.
• (Optional) Give a non-example if necessary to clear up any possible misunderstanding or confusion.
• (Optional) Use analogies, synonyms, or illustrations if you believe they will reinforce understanding.

Concept Example

Task

Write a task topic type when you need to explain how to perform a procedure step by step.

Suggestions for Task-Based Information

• In case a reader doesn’t have the necessary background knowledge to perform a task, provide a link to pertinent conceptual information at the beginning of the task topic.
• Precede the numbered steps with an introductory statement.

  Example: To create a widget, follow these steps:

• Try to limit each step to one action unless the second action is as simple as “…then click OK.”
• Where necessary, include explanatory text or results. To keep steps relatively short, show the explanatory content in a separate, non-numbered paragraph below the step.
• If a step requires a decision and possible branching, use a table or bulleted list.
• Bold the name of UI elements that the user interacts with or clicks on.

  Example: Select Widget Model A from the list.

Task Example

Reference

Write a reference topic to provide supporting information for completing a task or enhancing knowledge. Reference topics provide factual information that you would look up rather than memorize.

While reference topics usually have a brief introduction, the primary content is usually a table or list. A list of recipe ingredients is an example of reference information that supports the important task of cooking.

In the 911 example, we could create a reference topic that lists all of the incident information needed when calling 911. We would then link to the topic from step 3 in the task example.

Reference Example

Again, these are simplified examples, but I hope they give you ideas about how you can transform your FAQs into topics. I also hope you will consider using a topic-based approach to structure and simplify your content.

As always, I welcome your comments.

Back to top

Recently, while trying to complete an online form, I needed help with a specific field. The field had a question mark icon next to it. I clicked the icon, and a separate window opened. The window displayed a long, scrolling list of anchor links leading to a long, scrolling group of FAQs.

I scanned the list and clicked through to what appeared to be a promising match near the bottom. I read the answer, but it was unrelated to what I needed to know. After tedious, endless scrolling through FAQs, I couldn’t find anything related to my question. I finally opened a new tab and used a Google web query outside of the site.

Sound familiar?

Many websites use Frequently Asked Questions (FAQs) as the primary means of providing help for customers and other visitors. While FAQs may sometimes work in certain contexts, they often make finding answers more difficult.

Just ask Laura Creekmore. In her August 2011 post, I’m Going to Stop You Before You FAQ Again, Laura explains why FAQs are bad and suggests ways in which you can avoid using them. I want to supplement Laura’s great post with suggestions for how you can rewrite FAQs as topics.

The Trouble with FAQs

So why are FAQs badly overused? Here are some reasons.

Too Many Interrogative Words

When we write FAQs, we guess at how users will ask a question. We use strings of interrogative words that can make browsing and scanning difficult. And web users browse and scan a lot. We sometimes add so many words that our content may not readily appear in search results.

Extraneous Words

FAQs often include scene-setting statements with a lot of extraneous words. This type of construction can obscure the words that are relevant to what users want to know.

Lack of Context

FAQ pages often have no contextual relationship with the content that they represent.

Think Topics

The widespread use of FAQs is easily understandable. When site visitors search or browse for information, they ask implied questions through their search queries and the pages they visit. We who are responsible for providing help try to anticipate how they might phrase their questions by writing FAQs.

We can just as easily turn questions into topics. Topics are discrete chunks of information that can enable readers to accomplish the following:

• Understand a concept
• Perform a task
• Look up information
• Solve a problem
• Establish where they are in a hierarchy of information

Benefits of a Topic-Based Approach

A topic-based approach provides the following benefits:

• Uses consistent structures to establish a repeatable, predictable pattern for finding information
• Uses headings and subheadings to break up longer topics, supporting the ability to scan text
• Separates supporting information from how-to information so that site visitors get exactly what they need

Types of Topic

Table 1 lists the three most common topic types in web writing and describes the purpose of each. If you are even marginally familiar with Information Mapping or the Darwin Information Typing Architecture (DITA), you will recognize these.

Table 1. Topic Types

Examples of other topics include:

• Overview: An organizational topic that serves as a landing page for a site section
• Process: Describes a step-by-step process and identifies the doer of the action for each step
• Troubleshooting: Used in help information for software applications; provides error message text, explains the action that caused the message, and offers a recommended solution.

In upcoming posts, I will expand on the three main topic types and provide examples. In the meantime, I would like to know what you think about FAQs as a help mechanism. Do you find them useful? Why or why not?

Back to top

Since its introduction in early 2006, MadCap Flare™ has maintained a steady course of evolution. Flare users have fostered this evolution through proactive feedback.

MadCap obviously listens. Each new version of Flare has shown that the company understands its users, and Flare 7 is no exception. Packed with impressive new features and enhancements, Flare 7 provides full support for information development teams and their workflows.

Setting up Your Infrastructure

A typical information development project requires setting up an infrastructure for organizing, managing, and sharing project files. Flare 7 provides three new features that support resource sharing and team collaboration.

External Resources Pane

While Flare continues to support one-way linking to source files, the new External Resources pane dramatically extends file linking capability. You can connect to local and network folders outside of your project and create mappings to files in those folders. As long as you maintain the connections, you can then access the files and folders from any project.

You can also establish bi-directional synchronization between a file in your project and an external file. This is useful if you are the “keeper” of a specific master file and need to ensure that everyone has the latest version.

SharePoint Explorer Pane

If your team uses Microsoft SharePoint for file management and source control, you can integrate Flare 7 into your SharePoint workflow. The new SharePoint Explorer enables you to connect to a SharePoint server and use check-in and check-out commands to work on topics. As an alternative, you can copy a file to your project and use the same bi-directional mappings supported by the External Resources pane.

Subversion Integration

Apache Subversion (SVN) is a popular, open-source solution for managing file libraries. Flare 7 has native support for Subversion. You can bind a new project to Subversion during creation, or you can bind an existing project using the Project Properties window. No third-party plug-ins are required.

Developing Your Content

With your infrastructure in place, you’re ready to concentrate on writing. The Flare 7 XHTML Editor provides a streamlined authoring environment with several useful new features.

Editing Toolbar Enhancements

The editing toolbar has two new, notable additions:

• Preview button: This button has been enhanced to display a drop-down list of all output types (called targets) in your project. You can easily preview the current topic as HTML or PDF without changing the primary target.
• Insert Snippet and Insert Variable buttons: These two buttons enable you to quickly insert snippets and variables (reusable text blocks and text strings). This facilitates faster editing than using the equivalent menu commands.

Auto Suggestion

Flare 7 replaces the former IntelliSense feature with an optional but much smarter feature called Auto Suggestion. This new feature analyzes what you type and offers suggestions for completion. Those suggestions come from system variables such as Long Date, as well as from your custom variables and snippets. Suggestions appear in a pop-up window, and you can use the keyboard to select and accept an entry.

Auto Suggestion gives you more control over automating text entry than its predecessor. You can add a custom Auto Suggestion file to your project and use the file to build a preferred list of frequently used words and phrases. This “trains” Auto Suggestion to recognize text that you frequently type.

Structure Bars with Modified Design

The Structure Bars in the Flare editor provide a visual representation of the XHTML structure used in a topic. In previous versions of Flare, the bars represented text and table formatting separately.

In Flare 7, the separate Structure Bars for tables are no longer present. Table structure has been integrated into the main Structure Bars. In addition, the bars provide a more granular view of the table markup. You can drill down to the cell level and see the interior tags (such as lists) that are applied to cell content. This useful enhancement gives the editor a much cleaner, less cluttered appearance.

New Paste Options

Pasting text into Flare from another source has sometimes been unpredictable. Flare 7 replaces the rather intimidating Paste Text window with a new, powerful Paste icon.

Flare’s Paste icon resembles that of Microsoft Word, but the pop-up menu in the Flare version gives you more options: paragraph, paragraph block, inline text, table, or list. I find the inline text option especially useful for integrating pasted text into the destination text without having to clean up formatting.

When you paste tables or table text, the Paste icon’s dynamic pop-up menu shows commands for table formatting. The menu changes according to whether you are converting a table to text, cutting columns, cutting rows, or merging tables. This article further discusses Flare 7 table enhancements in a later section.

Equation Editor

Flare 7 supports the Mathematical Markup Language, or MathML. Along with this capability, MadCap has added a new Equation Editor to enable writers to build equations and insert them into topics.

The Insert – Equation menu command launches the new editor, which offers templates for various types of equations. You can view equations in either of two views: Design or Source. The latter view shows the MathML markup.

When building output, Flare converts equations into images. XHTML output renders them as raster images, and PDF output renders them as vector images. For optimal accessibility, the Equation Editor provides options for adding a screen tip and alternate text (alt text) attribute to the equation properties.

Enhanced Support for Table Insertion and Editing

Options for inserting and editing tables are significantly enhanced in Flare 7:

• Insert Table button: This new button appears on Flare’s Text Formatting toolbar. Similar to the equivalent button used in Microsoft Word, clicking the button displays a drop-down grid on which you can hover the mouse pointer down and to the right to select the desired number of rows and columns.
• Convert table to text: As an example, if you select a nine-cell table and select the Convert to Text command, Flare creates nine paragraphs. The dynamic Paste icon remains available, enabling you to try other paste options.
• Convert text to table:ƒ You can accomplish this task by simply selecting the text, then using Flare’s Table menu command sequence (Table – Insert – Table) to set up the table structure.
• Sort rows: You can sort table rows in ascending or descending order.
• Merge tables: If you have two differently styled tables separated by an empty paragraph, you can determine which style takes precedence when you delete the paragraph and merge the tables.
• Reset Local Cell Formatting: Unlike in previous versions of Flare, this command affects only selected cells, rather than the entire table.

Enhanced Support for Table Styles

The Flare 7 Table Style Editor looks similar to the previous editor, but it includes many improvements. It also gives you much more control over table properties and style usage.

Using the new editor, you can

• specify that certain properties such as padding be different in specific areas of a table;
• exert more control over row and column patterns, including their names and their behavior;
• create a custom pattern type for rows or columns and use it to override other patterns in specific instances of styled tables;
• use a new Medium drop-down list inside the editor to specify different settings for different style sheet media (online and print) in one place; and
• use a new Apply Style command to apply a table style to selected files, folders, or to all topics in a project. This is a significant and welcome improvement.

Quick Response (QR) Codes

Flare 7 enables you to insert Quick Response (QR) codes into topics. A QR code is a type of barcode designed to be read by devices such as smartphones. QR codes can encode text, a URL, an e-mail address, a contact card (vCard), or SMS message text. To read a QR code, your phone must have a special reader application. Several readers are available at no cost.

In describing one use case for QR codes, MadCap suggests that you could provide a code for employees who are doing field work and need access to your online help. If you design for this use case, I recommend that you use Flare’s Mobile skin (introduced in Flare 6) to design your help for viewing on a mobile device.

Support for New Vector Image Formats

Flare 7 supports three new vector image formats:

• Scalable Vector Graphics (SVG), an XML-based format
• PostScript (PS)
• Encapsulated PostScript (EPS)

These file types primarily serve to provide better image clarity in printed output. If the images are used in WebHelp output, Flare converts them to .png files.

Conducting Editorial Reviews

Because Flare is a topic-based writing tool, you can send individual topics for review at any point in the information development cycle. I find that clients often prefer this approach, as they don’t like to be overwhelmed by reviewing a large help system or PDF guide all in one go, especially if they are seeing the content for the first time. When your completed work is ready for production, clients can then view topics that they have already read in the context of the full product.

Previous versions of Flare supported author annotations, topic reviews, and contributions by outside authors. Flare 7 extends all of these capabilities with enhanced review features. Some features are designed to work with MadCap’s new Contributor product, which consolidates the former X-Edit product family. This review discusses only the features that are native to Flare 7.

The menu bar now includes a Review menu. This menu and the equivalent Review toolbar now include a Track Changes feature. You can set options for Track Changes using the Review Options tab, accessible from the Review menu. For example, you can specify your user name and initials. You can also specify how changes appear in your files.

The Track Changes feature follows industry-standard conventions. You can show or hide changes, navigate through changes, and accept or reject changes. Annotations (author comments), which previously appeared in a separate pane, now appear in the XHTML Editor.

Building, Analyzing, and Refining

As you develop content, you typically build output in designated formats such as WebHelp and PDF. As you build output, the Flare compiler displays messages to notify you of any issues that you need to address. One of those issues is accessibility compliance.

Accessibility Features and Enhancements

While Flare has always included features to support web accessibility requirements and standards, Flare 7 takes accessibility to a new level.

All Flare targets (output configuration files) for WebHelp and PDF now include a Warnings tab for accessibility checking. If you turn on the warnings, the Flare compiler will check for accessibility problems during a project build.

The compiler identifies and reports the following types of problems:

• Images, equations, and QR codes that are missing an alt text attribute
• Tables that have no caption or summary
• Tables without a header row
• Form elements with missing labels
• Frame elements without a title or name.

You can click the compiler’s Save Log button to save a date-stamped log to the Reports folder in your Flare project. With the log file open, you can double-click on any row to open the corresponding file that produced the message.

Missing alt text attributes are a common accessibility issue. Unless you have added screen tip and alt text to an imported image before inserting the image into multiple topics, some instances of that image may not include the attributes. Fortunately, Flare 7 includes a time-saving feature that automates the process of inserting screen tip and alt text attributes in multiple instances of an image:

1. Open any topic that references the image.
2. Select the image.
3. Right-click and select Edit Picture.
4. In the Edit Picture window, follow these steps:
   1. Add the Screen Tip and Alt Text attributes.
   2. Check the box labeled Apply the alternate text and screen tip to all image references.
   3. Click OK.
      Flare applies the attributes to all instances of the same image.

During PDF compilation, Flare automates the following conversions for accessibility:

• Converts each alt text attribute to its PDF equivalent so that a screen reader can properly describe each image.
• Converts XML lang attributes to their PDF equivalent for the entire PDF file and for any languages that may be applied to specific XHTML elements.
• Converts table structures to their PDF equivalent so that screen readers can properly read them.

The PDF target includes a PDF Options tab, with some options that duplicate certain settings found in Adobe Distiller and Acrobat (such as Image Compression and Initial View). You will also find a Generate tagged PDF setting, which enables you to generate the PDF build with structured tagging. The tagging is similar to the structure of the source XHTML files in your project. Although PDF tagging increases the file size, it is required for making a PDF file accessible to screen readers. If you have ever post-processed a PDF file to add tagging, you will appreciate the automation that Flare now offers.

New Reports

To further analyze your project output, you can add a new report file, select what you want to include in the report, and then generate the report. Flare 7 adds a number of useful report options for analysis.

One of the available report categories is Context-sensitive help (CSH). Let’s say that you have generated a report to analyze your CSH setup. The report lists several topics under the category Topics Not Linked By Map ID. You can quickly map those topics using Flare’s Alias Editor.

Redesigned Alias Editor

New help authors often find setting up context-sensitive help a bit daunting. The interplay between alias (.ali) files and header (.h) files can be confusing.

The redesigned, elegant Alias Editor in Flare 7 simplifies the process of mapping topics to identifiers and building a header file. The editor has a clean layout, with a Content tree structure on the left, and an Identifiers table on the right. The first column in the table marks unassigned identifiers with an orange icon. Assigned identifiers have a green icon.

The Alias Editor enables you to add identifiers to single files, selected multiple files, or the entire project. You can associate a header file with the alias file and generate its contents.

Assigning topics to identifiers is easy:

1. Select an unassigned identifier in the Identifiers table.
2. Right-click a file in the folder tree on the left.
3. Select Assign topic to selected identifier. The Identifier table adds the file name and the path.

As you assign identifiers and set up your context-sensitive help, Flare builds a header file that you can give to your software development team.

Summary

MadCap Flare has always provided a comprehensive feature set for single-sourcing and content management. Flare 7 extends these capabilities to cover the entire spectrum of information development. I encourage you to download and evaluate a trial copy.

Back to top

Looking to learn MadCap Flare? If you’re a new Flare user, you’re probably feeling a bit intimidated. Features abound, and the learning curve is steep.

You can embark on several learning paths to Flare mastery:

• Try Flare’s excellent, comprehensive online help. The problem is, you may not understand certain concepts well enough to know where to start.
• Take a MadCap course. They offer a Basic-to-Intermediate class for beginners. They also offer Advanced CSS and Single Sourcing classes.
• Try the excellent topical guides (PDF) under Flare’s Help > Guides submenu. The guides provide a structured, linear learning approach.

All three options are great learning paths, but what if you want a comprehensive reference book?

Easy. Buy Five Steps to MadCap Flare by Lorraine Kupka and Joy Underhill. The authors are Technical Communication pros with over 40 years of combined experience between them. If you’re new to Flare, you can adopt their best practices from the start. If you’re an experienced Flare user, you’ll get a broad perspective that you can apply to existing projects.

Learning by Example

For readers who are new to topic-based authoring, Five Steps gives an excellent primer in the short chapter called Document Basics. The organization of this chapter—and all chapters, for that matter—exemplifies the practice of modular writing. The authors organize Information in easily digestible chunks with clear labeling. They also provide short reference sections such as Terms to Understand and include brief, easily scannable tables to help you sort out various options.

A Quick Tour provides a brief orientation to the Flare interface, emphasizing the conventions used in many of the side panes and settings windows. The chapter includes plenty of annotated screen captures to help orient you to the UI components.

Breaking your Stride

Don’t make assumptions about the notion of learning Flare in five steps. Kupka and Underhill have crafted each “step” as a category that subsumes a large chunk of knowledge. I’ll summarize the steps here and add some of my own comments.

Step 1: Get Started

This step gives pointers for planning your first Flare project, teaches you how to the perform common tasks, and introduces you to Flare templates.

Many Flare users plunge into creating a project without pre-determining the nature of its content and purpose. Planning your Flare project gives you guidelines in the form of questions. For example, do you already have source content or do you need to create it? Will you deliver both online and printed versions? How will your content be reviewed? The authors provide a useful roadmap in table form to help you make the right decisions.

If you’re used to creating templates in applications such as Word or FrameMaker, you’ll find Flare’s template model to be far more versatile and expansive. A Flare project can serve as a template, and each of its internal files can be templates, too. You can save most files outside of a project and reuse them in multiple projects. Since most of them are XML files, you can view them in a text editor. Flare 6 introduced the Template Manager, which makes saving and reusing templates much easier. In the section titled Working with Templates, the authors recommend best practices for using templates and explain how to use the Template Manager.

Step 2: Learn the XML Editor

Although the Flare authoring environment works like a word processor, it’s packed with features that are unique to the application. Step 2 walks you through nine core tasks for learning and customizing your environment. De-cluttering your workspace suggests that you close the panes on the right to increase your viewing space. (I also recommend saving customized workspaces for various tasks.) The Learn More section covers key visual indicators such as the structure, tag, and span bars.

Step 3: Develop Content

In this step you learn how to work with essential content elements. Here’s a partial list of covered topics:

• Working with lists provides thorough coverage of single- and multi-level lists, including how to rearrange, sort, re-number, and merge them.
• Working with tables explains basic tasks such as inserting, deleting, and moving rows and columns. Since Flare also uses specialized style sheets for tables, the authors continue the subject of tables in the formatting section. I second their recommendation that you create and store table formats in templates for reuse.
• Working with images explains how Flare manages changes to images. This section thoroughly covers resizing images and explains how resizing affects their quality.
• Formatting your content and Customizing styles both provide advice for controlling the appearance of your online and print content. You can supplement this information with one of my recommended books on CSS.

Step 4: Create Navigation Aids

The Help authoring community has many lively online discussions about navigational elements included in application help. For example, whether to include or exclude an index always seems to rouse passion.

In Step 4, the authors avoid editorializing about what to include or not include in your projects. They simply explain how to add and manage all of the available aids that Flare offers:

• Creating a Table of Contents provides thorough coverage of how to add one or multiple TOCs and how TOCs support online and print output.
• Creating links provides a useful table that describes all of the types of links that you can add to a Flare project. It explains how to add each type, including the Related Topics help control.
  Tip: If you’re using Flare 6, don’t forget about the Link Viewer, which enables you to trace link paths and dependencies.
• Adding cross-references explains how to add cross-references for your print output. Flare has great power and versatility for creating and managing cross-references. For example, contextual page number references can detect whether a referenced item is above or below the discussion point.
• Creating index entries explains how to add index keywords to your projects by adding markers to topics. (Like Word and FrameMaker, Flare uses embedded markers.) This section also covers how you can vary index output by adding conditional tags to markers.
  Another Tip: I’m a big fan of the Index Explorer (View > Index Explorer), and it’s greatly improved in Flare 6. Use this feature to monitor the state of your index during project development.

Step 5

Step 5 is split into two sub-steps, with 5A covering printed output and 5B covering online output. In both sections, you learn to set up project components and build the output.

Step 5A: Create Print Output
The good news about creating print output from Flare is that once you set it up, you can easily update and regenerate the content. The bad news is that setting up printed output is arduous. In fact, I’ve written a six-part series covering Flare print publishing.

Fortunately, Five Steps gives you a logical, well-planned strategy that includes preparation and decision-making. The authors divide the process into nine tasks. They recommend that you start with a simple print document so that you understand how to build the components, then graduate to a more complex document with multiple sections.

I’m a fan of this approach. I typically create (1) a simple print setup for sending individual or groups of topics to reviewers; and (2) a more complex print setup for double-sided, multi-sectioned documents.

Step 5B: Create Online Output
This sub-step follows a similar progression to Step 5A. The main difference is that it focuses on online components such as master pages and skins. It also includes a useful Testing and troubleshooting section.

Supplementing Your Learning

The five-step process summarized in this review gives you the core skills you need to master MadCap Flare. But the authors didn’t stop there. Appendices A through H offer useful, detailed supplementary information, including the following:

• Appendix A: Planning Worksheets includes the following worksheet examples for Flare projects:
  • Defining content sources
  • Defining project outputs (Example: WebHelp, WebHelp Mobile)
  • Determining how reviews will be handled (Example: MadCap X-Edit, MS Word)
  • Establishing project settings (Example: location, source control bindings)
  • Recording your target settings (Example: master page, medium, condition tags)

  These worksheets help you with planning and tracking. They also provide a concrete trail for another author who might serve as your backup or who might eventually inherit your project.

• Appendix B: Import Content explains how you can import MS Word, FrameMaker, or HTML files into Flare.
• Appendix C: XML Reference summarizes the XML Editor UI elements, including toolbars, cursors, and shortcuts.
• Appendix D: Context-Sensitive Help eloquently breaks down the process of mapping topics to UI elements.
• Appendix E: Troubleshoot offers tips such as fixing broken links and interpreting build errors.
• Appendix F: Single-Sourcing focuses on Flare features used in single-sourcing content, including condition tags, snippets, and variables.
• Appendix G: DITA Import and Export explains how to get DITA content into Flare and how to export it from Flare.
• Appendix H: The Next Step provides a roadmap for exploring additional Flare features that are not covered in the book.

Summary

In Five Steps to MadCap Flare, Lorraine Kupka and Joy Underhill have provided a clear, easy-to-follow guide to mastering Flare. They start with tool-agnostic, sound advice on planning an information development project. In the Flare development context, they emphasize projects and templates as the key building blocks.

I also appreciate how the authors set best practice examples for all information developers to follow. They write in plain, conversational language. They use consistent conventions that facilitate ease in finding information. And they’re damn good teachers.

Buy the book now.

Back to top

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. The marker serves as metadata for associating the topic with a specified concept.

To insert a concept marker, follow these steps:

1. Open the topic.
2. Open the Concept Window: View > Concept Window.
3. 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:

1. Open a topic that contains a concept marker.
2. Select the following menu command:
   Insert > Help Control > Concept Link (A-link)
3. Select a term on the right.
4. Click the directional button in the middle of the window to copy the term to the left side of the window.
5. 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].

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, search for these Flare help topics:

• Inserting Related Topics Links into Topics
• Editing Related Topics Links

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, search for these Flare help topics:

• Inserting Keyword Links into Topics
• Editing Keyword Links

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, search for this Help topic: 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.

Back to top