MadCap Flare includes a vast array of documentation functions, many of which can streamline work processes, reduce costs and increase productivity. One of the most significant of these is the ability to apply conditions to project content. While not unique to MadCap Flare, the ability to apply conditions has significant value. In basic terms it. . MadCap's new help format. Designed for.NET applications (Requires.NET Framework 2.0). Can run from a file server. Not compiled. Viewed in the Flare Help viewer (free distribution).
Unlock the full course today
Join today to access over 13,000 courses taught by industry experts or purchase this course individually.
Course Info
- Duration: 3h 37m 35s
- Skill Level:Beginner + Intermediate
- Released:July 18, 2016
- Viewers:2,887
Learn the most in-demand business, tech and creative skills from industry experts.
Course details
MadCap Flare is a powerful authoring tool for creating technical documentation—help systems, service manuals, and more—in online and print forms like HTML5 and PDF. In this course, Neil Perlin first explores Flare's conventions and interface. He then explains how to create projects based on Flare 12's 'topic model.' Learn how to create projects, add content, add navigation to let users find information quickly, control the format of the material, define different outputs from a single project, and generate those outputs in any of 16 different formats.Related courses
Welcome
- [Voiceover] In this video, you'll learn about Flare's interface and how to customize it. I have a sample project up on the screen and let's take a look at the interface. First on the left hand side we see two tabs with their labels at the bottom left. They're called the Project Organizer and the Content Explorer. So the Content Explorer contains content topics, they could be graphics, and content control files, files called style sheets, for example, and various others. The Project Organizer pane contains control files and settings that apply project-wide. Table of contents for example or glossary, something called a skin which we'll explain. In the center is the editing pane and this is where, as the name implies, you'll edit your topics and all the other files that you can create in Flare, such as style sheet files and so on. On the right, this is where right now you're seeing the Help, Flare's dynamic Help. Many features display in the right pane for one time use, they're transitory, something like a Spell Check for example or a Search and Replace. So although you don't have to do this, what a lot of people do is they do whatever task they wanted to do using the right hand pane and when they're done, they close it. And to close it, you just click the x. And now I have more room for my editor. You'll find that there are other features that open by default as well in the left pane or the right pane. And to see what some of these features are you can click up on the menu on View. And what you're seeing here are most of the other features and control windows that you can open in Flare. For example, if I click Backups in the common group just to the left of center, the Backups pane opens up in the left pane. Others by default will open in the right pane. Let's take a look at the start page which we're actually looking at right now. If you don't see it, what you can do is click up on the menu on View and select Start Page in the common group. So on the left side of the Start Page, you've got quick access to basic tasks like Open an existing project or Create a new project and there's a list of your recently used projects. On the right hand side are various help resources and at the bottom right, partly buried is the News and Updates section which lists things like conferences at which MadCap will be exhibiting or presenting, information about new releases and so on. Also, Flare is set up following modern conventions as far as interface is concerned which means we have a global menu along the top and selecting any of these menu items displays the ribbon. We also have so-called local tool bars in different windows. So for example, if I open up the Content Explorer by clicking the Content Explorer label at the bottom left, what you see at the top is the Content Explorer's local tool bar. What's nice about the interface is that it is almost completely customizable. You can display whatever you want, move whatever you want wherever you want. For example, let's say that I want to move the Content Explorer pane, I don't want it where it is. And if you look at the Content Explorer pane's title bar, you'll see that to the left of the title is a little stack of horizontal lines, that's the Drag icon. To the right we have a pull down which lists various options, there's a pushpin which I'll show you shortly, and there's the x which obviously closes it. So let's go ahead and move the window. I'll click and hold on the little stack of horizontal lines and drag out. My window is now floating, so I can move it anywhere on the screen and if I have a dual monitors, I could actually move my Control windows onto the second screen and leave the first screen dedicated solely to content. I can also re-dock a window. And to do that what I do is I just click in the floating window's title bar, hold the mouse button down and move the mouse a little bit. And you'll see these docking aids, these little greenish, whitish squares. Move the mouse pointer over any of those squares and you'll see a shade that shows where that window will go when you release the mouse button. So, I've just docked it back at the left hand side of the screen. You notice that the tabs look a little different. They're not at the bottom left. They're regular die-cut tabs up at the top. What I can do is click that little pull down and select say Accordion Tabs, and we're back where we started. There might also be times when I want to get the window out of the way temporarily. I could close it, and closing it is easy, I just click the x and I can reopen it then by clicking on the View menu. But I might want to do something simpler, and there's a feature called Autohide. And if I click the pushpin, you notice how that whole left pane seems to disappear, but if you look at the left hand side of my screen, you can see the tab labels hanging there. And if I hover over any of them, that tab will pop open. So I'll hover over Content Explorer and it stays open. You notice that the pushpin is now pointing to the left because they're pinned against the screen. They stay open until I click off the window and then they close. So if I want to go back to normal view, I'll just click the pushpin again, it's vertical, and I'm back where I started. So when you start using Flare, sooner or later, you're going to experiment with the interface and get to the point where you're deciding, this is a bad idea, I want to go back. You could try to retrace your steps, but that's kind of inefficient. Instead, what you can do is click up on the menu, on Window, and then select this option Reset Layout at the right end of the ribbon. A message will ask for confirmation. Do you want to reset to the factory settings? You click okay and you're back where you started. So in this video, you learned about Flare's interface and how to customize it.Practice while you learn with exercise files
Download the files the instructor uses to teach the course. Follow along and learn by watching, listening and practicing.Download the exercise files for this course. Get started with a free trial today.Download courses and learn on the go
Watch courses on your mobile device without an internet connection. Download courses using your iOS or Android LinkedIn Learning app.Download on the App StoreGet it on Google PlayWatch this course anytime, anywhere. Get started with a free trial today.
Course Contents
Note: This article should not be construed in any way, sense, fashion, or form as officially related to Tenable Network Security, Inc., my employer. It is definitely not up to the brand guide, sorry about that, guys. Forgive me my occasional informality throughout. It's because welp.
As a part of my work as a technical writer with Tenable Network Security, I was tasked with creating a searchable version of our documentation website.
The goal was to provide users a way to search the content of all of our HTML-based help systems. Not just a way to search within the help systems individually, but a way to search all of them at once. Obviously, internal site searching is ubiquitous, and there are a vast number of ways to implement it. This particular approach utilizes a common piece of technical writing software.
TL;DR alert: In the following article, I give a high-level explanation of how I tackled this problem. If you're interested in how you can use Flare to implement a search engine (so to speak) on your website but want to avoid my waffling, skip to the bottom. You can't create anchors in LinkedIn articles apparently, so I included a giant picture of Navi, instead.
In the case of this implementation, the requirements (some handed down, some self-imposed) were the following:
- It should be free or very low cost.
- If possible, use the existing tools we have.
- There should be no delay in new content being available via the search (I didn't want to have to wait on indexing, though a pretty minor thing)
- When following a link from the search results, the content should display correctly. See below.
The Tenable technical writing team utilizes MadCap Flare in the day to day to produce content predominantly in Flare's tripane format. The tripane format utilizes frames to display a topic (architecturally, an .htm file rendered in an iframe) alongside a table of contents, functionally a wrapper for the topic.
One of the limitations of the tripane skin is that it is possible to access a topic file directly. When you do, the table of contents is not displayed (since the topic is not being displayed in a frame), which can leave a user without a clear indication of where in the hierarchy of topics they are, as well as preventing them from easily navigating to other topics in the help system.
MadCap Flare provides an option when you generate the help system that will embed a link in each topic that, when clicked, reopens the topic within the wrapper. For example:
If you do not enable this option, it is difficult to return to the framed view. Any subsequent topic you navigate to from the unframed topic will also be missing the wrapper. And even if you do enable the option, adding extra steps for navigating a website is undesirable.
This is an issue with searching MadCap Flare's tripane content even from major search providers such as Google and Bing.
I wanted to ensure that users would always be directed to framed, in-context content.
Hey, Flare does that!
Or, some of that, at least. For the HTML5-based formats, Flare constructs a fairly comprehensive client-based (i.e., Javascript-based) search system. Flare 11 introduced numerous fixes and improvements to previous version, and Flare 12 has continued that.
I explored some other options, but from the start it was evident to me that we could leverage Flare 12 to implement the search system we wanted. It immediately fit some of the criteria, primarily that there was no additional expense associated with implementing it, and the implementation would utilize software that our writers were already familiar with.
What happened next: A story of some failures with a happy ending
From using Flare, I had some anecdotal understanding of how the search functionality for the HTML5 Flare output was constructed. Basically, Flare iterates through topic files and extracts the words, topic titles, and URLs. I can't speak to how intelligent Flare is when it comes to phrases, word proximity, classic SEO stuff, but suffice to say they were not key to implementing the search on our site.
Attempt 1:
I said, 'Okay. Here I go. I am going to copy all of the .htm files that already live on our website and just dump them into a new Flare project and see how the search works.'
The answer was that it did. It worked pretty darn well. Too well, actually. Files that weren't normally indexed when you generate a Flare project, such as the .htm files that support context-sensitive help, were being pulled into the search results.
Since the search did work on the most fundamental of levels, the next logical step was to try and clean up the results.
Attempt 2:
In another new Flare project, I copied in only the .htm files from our website that corresponded to actual topics. I did this manually, which took way too much time.
This worked really well. The search results were valid, reliable, and clean. Then I decided to click a link in the search results, a step I neglected in my first attempt.
Unfortunately, this is where we encountered the classic search engine issue: the topics in our tripane-format help systems weren't displaying in frame. The links in the search results went directly to the topic files themselves.
An Inventory of Problems
After these attempts, three issues were clear:
- Manually copying the files you wanted to make searchable was time consuming. Way, way too time consuming, especially given the inevitable expansion of product lines, available features in software, all the usual stuff that makes technical documentation continually grow. This process would not be manually sustainable. Especially if, as things got more complex, there were also files you DIDN'T want to include in the search.
- The stupid topic files needed the stupid table of contents. Because of the historical nature of some of the existing Flare documentation, we also couldn't rely on the 'Open topic with navigation' feature being enabled help system to help system. It wouldn't be viable to release a search function on our website that would maroon users on individual topics.
- We needed a static Flare project that could be used to consistently generate search results that would match our actual website.
In the case of the third issue, I created a version-controlled Flare project (in our case, we use git) that would serve as the compiler for our searchable website. The output of the Flare project is skinless (that is to say, it doesn't utilize either the tripane or the top nav formats that are the common staples of Flare output), and primarily consisted of the website's main page. Since we were using Flare, we added a search bar proxy to provide the actual text box where users could type their search terms.
The other two issues were still a problem, though.
The Resolution: I cheated
I'm a big fan of AutoHotkey, a language that has its origins in building hotkey-based macros. Now, it's a comprehensive, straightforward, and efficient scripting language for Windows (which is perfect, because Flare is only supported on Windows). And so, confronted with the idea of having to do work (my greatest motivation being 'How do I do less of it?'), I created two utilities to support our workflow.
The first is a dynamic script that pulls .htm files from any number of specified folder locations and delivers them in a 1:1 folder structure to the Flare project. The script is also designed to read a filter file, which allows us to easily specify files, folders, and complete directories that we don't want included in the search results. For other writers on the team, this turns the process of gathering the necessary files into a double click of the mouse.
The second script is more complex, and does the following in order:
- Builds the Flare project that contains the files we want to be searchable.
- Analyzes the output and identifies which directories contain tripane-formatted topics, and which contain any other sort of formatted .htm files (top nav or otherwise).
- Rewrites the URLs in the appropriate SearchTopic_Chunk.js and SearchUrl_Chunk.js files.
- Cleans stale files from the website to avoid any unexpected search congestion/errors.
- Copies over only the files specifically required to make the search functional, specifically the main website page, the search results page, and the data files that facilitate the search.
- Generates a sitemap for the whole website (normally an option in individual Flare projects, but we wanted our sitemap to include multiple Flare projects as well as non-Flare files). This isn't important for the search feature of the website, but is just a happy bonus.
By rewriting the search chunks, I was able to adapt the search results to account for tripane content. When you click a link to a tripane-formatted topic, it correctly appears in the table of contents.
Frankly, the scripts make life a lot easier.
'HEY LISTEN IF YOU SKIPPED DOWN FROM THE TOP THIS IS WHERE YOU SHOULD START READING IT'S COOL I DON'T BLAME YOU' - Navi, feeling social
A Summary, if you also want to try it
The automation I use is only to ease the steps required to make the searchable site work, though it isn't really required. Here I assume that you probably won't be writing scripts.
This summary also assumes working/advanced knowledge of MadCap Flare. Note that this approach definitely is an out-of-the-box method that I can't imagine is supported by MadCap in any way, shape, or form, so I wouldn't bug their support if you have problems with it.
If you want to use Flare like a search engine for your website, the primary concerns are these:
Project file structure
You will need to keep a Flare project that simulates your website. That is to say, the folder structure in your Content Explorer in said Flare project must be a one-to-one match of the directory structure on your website. I would not recommend including this project in your actual website directory (if you have the option to).
Target settings
In the HTML5 target for that Flare project, on the Advanced pane, you must ensure that the Do not use 'Content' folder in output option is enabled. This preserves that 1:1 directory structure.
In the HTML5 target for that Flare project, on the Skin pane, you must set the skin to (none).
Required files
You should only include files that you want to appear in search results in that Flare project. The more junk you fill it with, the longer it takes the compiler to run, and the more diluted your search results are. You don't just want to copy your complete website into the Flare project.
One or more pages need to include Flare's search bar proxy. Whether you insert the proxy using Flare, or just copy the proxy code to an existing page, that's up to you. If you do the latter, that page must exist at the same level as the Data folder that is created when you build the HTML5 output of the Flare project.
While not required, if you want your search results page to include a search box (just like every search engine), you'll need to do the following: In the Flare project, you need to create a page that contains both the search bar and search results proxies. It doesn't matter what the file name is, Flare is intelligent enough to use the topic that includes the search results proxy to display results. For what it's worth, the auto-generated default is Search.htm, which is what I used. If you skip this step, your search results will not have a search bar at the top.
Putting it on your website
The only files you absolutely need to copy from your HTML5 output to your website are the following:
- The .htm file or files that include the search bar proxy.
- Search.htm, or the topic that you included the search results proxy in.
- The Data folder.
Everything else is just used to generate the search and is not necessary.
Rewriting search chunks
Modifying the search chunks is only necessary if you want to support the tripane format. The find-and-replace to fix this is actually pretty straightforward.
You should perform the following in each SearchTopic_Chunk<x>.js and SearchUrl_Chunk<x>.js file.
If all content is tripane format and all projects are using the Content folder:
- Find: 'Content/'
- Replace: 'Default.htm#' [Replace 'Default' with whatever you've specified for Output File in your target]
If all content is tripane format and no projects are using the Content folder:
- Find: '<foldername>/', where <foldername> is the name of the folder that contains topic files.
- Replace: '<samefoldername>/Default.htm#' [Replace 'Default' with whatever you've specified for Output File in your target]
If the content is of mixed format, you'll need to find specifically the folders that contain tripane stuff, like:
- Find: '<foldername>/Content/', where <foldername> is the name of the folder that contains topic files.
- Replace: '<samefoldername>/Default.htm#' [Replace 'Default' with whatever you've specified for Output File in your target]
If the content is both of mixed format and some are using Content folders and some aren't, you'll need to be even more focused in your approach, but a combination of the above terms should still work for you.
Summary of a summary
I won't say 'it's as easy as...' but at the highest level, the steps are fairly fundamental: copy files to project, build project, copy specific files back to website. In the final step, I'd suggest deleting the existing Data folder before you bring in the new one. I haven't seen any errors yet with overwriting, but a clean environment is always better.
About the Writer
Matt Williams is a technical writer at Tenable Network Security, Inc. He works out of Roanoke, VA, where he sits in a basement and tries to figure out new and exciting ways to break MadCap Flare, and clever implementations of automation that will one day replace him at his job.
If you have any questions about this article, comments, thoughts, etc., feel free to contact Matt at [email protected].