Many issues that can easily creep into new or legacy projects can be hard-to-find and/or fix. MadCap Analyzer can find and repair many of these issues. Four issues that often occur in MadCap Flare projects are multiple instances of the same text in your files, hard-coded company/product names, duplicate styles, and files not included in your outputs.
Most of the issues that Analyzer finds with a Flare project can be fixed either in Analyzer, or in Flare. Both tools detect the changes and update their display and analysis of the file in real time. A few issues require you to open the project in Flare and correct the issue in Flare.
1. Running the Frequent Segments Report
Analyzer can find all instances of text with punctuation that are identical. These instances can and should be converted to snippets. This reduces the need to find and edit all the instances if you need to make a change. Instead, you edit the snippet and all the instances are automatically updated.
Click View>Suggestions>Frequent Segments to display the Frequent Segments window, which displays all the frequent segments detected by Analyzer.
For example, in the project analyzed, there are 40 instances of "The number of elements in the array."
You can convert each segment to a snippet within Analyzer and Flare detects the change(s) to the file and updates its display if it is open or the next time you open the file in Flare. To convert a segment to a snippet, select the row and click Create>Create Snippet... from the local toolbar or right-click the row and select Create Snippet...
In the Create Snippet dialog, enter a name for the snippet and click Create. It's a good practice to name your snippet so you or other writers will easily be able to identify the snippet you want to edit or change. For example, in this case, I used the full text of the snippet. If the snippet text is long, use the first phrase or some other meaningful subsection of the snippet as the filename.
Analyzer can apply the snippet to all the referenced topics. In the Apply Snippet dialog, click Yes to apply the snippet. For safety, Analyzer archives the current version of the referenced topics in a Backups Folder.
After applying the snippet to the referenced topics, Analyzer displays a confirmation dialog with the number of files updated.
If you want to undo the new snippet, you can restore the files to their previous state using Analyzer's Backups Pane.
2. Running the Variable Suggestions Report
Analyzer can find all instances of text that match existing variables in your project. You can replace these multiple instances of "hard-coded text" with the corresponding variable. One common scenario is replacing company names or product names with a variable. It is much easier to update one variable than searching and replacing for every instance of either company name if your company is bought or product marketing changes the product name, often just before deploying a new version.
Click View>Suggestions>Variable Suggestions to display the Variable Suggestions window, which displays all the content that matches existing variables detected by Analyzer.
For example, in the project analyzed, there are many instances where the company name is hard-coded in the project. You should change these instances to a variable to make maintaining your project easier.
To convert content into a variable, select the row and click Apply... from the local toolbar or right-click the row and select Apply...
When you are more familiar with Analyzer, you can select several or all of the rows by selecting the first row, holding the Shift and Ctrl keys down, and clicking the last row you want to select. In the Apply selected suggestions dialog, click OK. For safety, Analyzer archives the current version of the referenced topics in a Backups Folder.
After converting the selected text with the variable, Analyzer displays a confirmation dialog with the number of files updated.
If you want to undo the operation, you can restore the files to their previous state using Analyzer's Backups Pane.
3. Running the Duplicate Styles Report
Analyzer can scan your style sheets and report on all styles that have identical definitions. These are called "duplicate styles" in Analyzer. You can have duplicate styles for a number of reasons:
- You inherited a legacy Flare project from another writer, not expert in using Flare or styles.
- You have a project converted from another tool, where styles weren't rigorously adhered to.
- Your project was worked on by one or more writers unused to working with styles.
You should remove duplicate styles in your style sheet because your style sheet should be easy to read. This has the added benefit of making it much easier to find and select the desired style to apply to content.
Click View>More Reports>Duplicate Styles to display the Duplicate Styles window. Styles that have the same definitions are shown in adjacent rows, with each set alternating between having a white background and the next set is shaded. You can modify one of the matching styles to have a different definition or delete one of the duplicate styles.
To open the style sheet containing the duplicate styles, double-click a row to open the style sheet in Analyzer. You can also select the row and click File>Send to Flare to open the style sheet in Flare. The following shows a section of the style sheet for this project with some of the duplicate styles shown.
If you have duplicate styles, view their definitions in the style sheet to determine if you should modify the attributes of one or the other styles, rename one of the duplicate styles, or remove one of the duplicate styles. If you decide to delete one of the duplicate styles, you should look at your existing styles and delete the style that breaks the pattern of your named styles and/or select the simplest style name. For example, in this style sheet, a good approach would be to delete the h4.Heading_4 duplicate style. Select the row for the style to delete, right-click the row, and click Delete. Using a style name of h4 is much simpler and intuitively obvious. Use this approach for all duplicate styles in the report.
4. Running the Topics Not In Selected TOC Report
Analyzer can scan a Flare project for files in the project that haven't been assigned to a specified table of contents (TOC). This can happen in any project but especially in large projects or if you are using conditions to single-source a project for multiple outputs or audiences.
This window displays a list of all topics that have been created in the project, but they have not yet been linked to any items in a TOC. A drop-down filter lets you select a specific TOC to analyze, or you can select "all" to analyze all TOCs in the project.
Click View>More Reports>Topics Not In Selected TOC to display the Topics Not In Selected TOC window.
Double-click a row to open the topic in Analyzer. You can also select the row and click File>Send to Flare to open the topic in Flare. Review the topic to determine if it is an old, obsolete, extra, "work in progress" kind of topic, "possible future feature", etc. and should not be included in your table of contents. If you decide the topic should be in one or more TOCs, you will need to open the project in Flare, open the TOC(s) the topic should be added to, and add the topic to that TOC.
Tip: If a topic is a "work in progress" or "possible future feature" topic, consider creating a directory for each type, under your Content directory, name them appropriately and clearly, and move the relevant topics to your new directories. This will help you and other writers who work on this project by clearly identifying topics that should not be included in the TOC.
Summary
To review, four recommended Analyzer reports you can run on your Flare projects to make your Flare project easier to maintain and have a clean project:
- Frequent Segments - These are instances of duplicate text in your Flare project. You should convert these to a snippet so you only need to update one file, the snippet, when that text needs to change and all the snippets will automatically update.
- Variable Suggestions - These are instances of hard-coded text in your Flare project that matches variables already defined in the project. You should convert these instances to the appropriate variable. Again, it is much easier to change one variable than search and replace for all instances of that text in your project.
- Duplicate Styles - These are styles with different names but the same definition in your Flare project. These not only complicate your style sheet but make it confusing for writers to select which style to apply to content.
- Topics Not in Selected TOC - These are topics (files) in your Flare project that have not been included in a specified Table of Contents (TOC). There are many reasons why they might be there but you should review them to determine if they are topics inadvertently omitted from one or more TOCs that should be in a TOC or topics you can delete or move to another directory because they are "work in progress" or a draft of a previously-planned feature that was dropped from this release. In the latter case, it's good to keep those drafts in your project in case the feature is revived.
Analyzer is a powerful tool that can scan, detect, and help you fix issues in a Flare project. Analyzer has many reports available that can make working with your Flare projects easier to develop and maintain including the following elements of your project:
- Undefined items
- Used /unused items
- Links
- Undefined items
- Miscellaneous file / topic items
It is well worth your time to consider purchasing Analyzer, learn about all the reports available in Analyzer, and use those reports. Using Analyzer in conjunction with Flare will make your project easier to manage/maintain and enable you to find and fix issues that otherwise are hard, or at least, time-consuming to find.
