# ImprovementSoft: Documentation Infrastructure That Scales
> Engineering services and MadCap Flare plugins that eliminate structural fragility, automate manual waste, and scale documentation without chaos.
This file contains all documentation content in a single document following the llmstxt.org standard.
## Release Notes - AI Helper Plugin
## 1.0.34
### π Bug Fixes
* **LLMS.txt β Add Description: meta description lost in HTML5 output** β fixed a bug where descriptions added through the *Add Description* dialog were inserted into a second, namespaced `` block instead of the topic's real ``. Flare ignored the namespaced block during target generation, so `` never reached published output or downstream LLMS/RAG pipelines. The dialog now reads and writes the topic's real `` directly. Topics already corrupted by earlier versions are migrated automatically: opening the dialog populates the textbox from the orphan block (so the previously-entered description is visible), and saving moves it into the real `` and removes the orphan.
## 1.0.33
### π Bug Fixes
* **Template add/edit fails on OneDrive-synced Documents folders** β fixed `FileNotFoundException` when adding or saving prompt templates on systems where My Documents is redirected to OneDrive. The `Directory.Exists()` check could return a false positive for cloud-only OneDrive placeholders, causing the directory creation to be skipped. All file-write paths now unconditionally ensure the target directory exists.
## 1.0.32
### π Bug Fixes
* **LLMS.txt content truncation** β fixed critical bug where the content extraction regex stopped at the first nested `` pair, discarding most of the page content (tables, dropdowns, nested sections). Replaced with a div-depth counting algorithm that correctly handles arbitrarily nested HTML.
* **Tables with structural tags** β tables wrapped in ``, ``, ``, or containing `
`/`
` elements now convert correctly. Cell content preserves inline formatting (bold, italic, links, images) and pipe characters are escaped.
### β¨ New Features
* **List conversion** β `` and `` lists are now converted to Markdown (`- ` and `1. ` syntax), including nested lists and lists inside table cells.
* **Image conversion** β `` tags are now converted to `` Markdown syntax. Flare spacer images (`transparent.gif`) are automatically removed.
* **MadCap element handling** β MadCap-specific elements (`conditionalText`, `expanding`, `toggler`, `keyword`, `concept`, MCDropDown structures, KeepTogether divs) are now pre-processed so their content is preserved in the Markdown output.
### π§ Improvements
* Extracted shared HTML-to-Markdown conversion code into `HtmlToMarkdownConverter` to eliminate duplication between LLMS.txt and Markdown Target generators.
* Added h5/h6 heading support to the conversion pipeline.
## 1.0.31
### π Bug Fixes
* **Glossary Term Processing** β fixed inconsistent behavior where complex HTML files (tables, special characters) would fail XML parsing, causing glossary definitions to appear inline instead of being properly handled. Rewrote processor using regex-based parsing for reliable operation on all HTML5 output.
## 1.0.30
### π Markdown & AI Docs
* **Glossary Term Handling** β new setting to control how glossary term popups are processed when generating Markdown. Options: remove definitions (default), keep inline, or append as glossary section at end of file.
### π§ Topic Splitter
* **Progress Bar** β visual progress feedback during topic splitting with real-time phase updates.
* **MadCap Naming Conventions** β generated file names now follow MadCap best practices: hyphens between words, title case, removal of minor words (a, the, in, on, etc.), and Swedish character support.
## 1.0.29
- Enhanced selection robustness in MadCapHelpers and XmlHelpers to provide better error messages and fallback for complex or partial selections.
- Support for converting HTML tables directly into Markdown.
## 1.0.28
### π Markdown & AI Docs
* **Smart Bookmark Control** β new setting to control bookmark links when converting Markdown to XHTML. Only unreferenced bookmarks are removed, preserving internal document links.
## 1.0.27
### β¨ Highlights
* **Snippets now work with Track Changes** β no more missing replacements.
* **New "Apply Snippets" tool** β automatically replaces matching text with snippet references.
* **Live snippet preview** β see the content before applying.
* **Smarter matching** β flexible options for exact, loose, or fuzzy text detection.
### π Markdown & AI Docs
* **Generate Markdown Target** β export clean, LLM-ready Markdown from your Flare output.
* **Automatic cleanup** β copies only Markdown, images, and essentials.
* **One-click "Generate LLMS.txt"** β builds Markdown and llms.txt in a single step.
### πͺΆ Quality & UI
* Cleaner icons, improved progress windows, smarter folder handling, and bug fixes throughout.
## 1.0.26
- **New Markdown-to-Flare Mapping System**: Added comprehensive functionality to map Markdown elements to Flare-specific XHTML with custom CSS classes and element transformations. Users can now configure how Markdown content is converted when pasting into Flare, including support for changing element names (e.g., `` β ``, `` β ``) and applying custom CSS classes.
- **Element and Class Mapping**: Support for both class-only mappings (`"myClass"`) and element+class mappings (`"span.myClass"`), allowing complete control over how Markdown formatting is transformed into Flare XHTML structure.
- **Enhanced Options UI**: Added new "Markdown to Flare" settings panel in the Options window with individual configuration options for bold, italic, underline, headings (H1-H3), lists, and code elements. Each setting includes helpful examples and tooltips.
- **Smart Markdown Processing**: Updated all Markdown-to-HTML conversion commands to automatically apply the configured mappings when pasting Markdown content into Flare topics, ensuring consistent formatting and structure.
- **Comprehensive Unit Testing**: Added extensive test coverage for the new mapping functionality, including element transformation, class application, and integration testing.
- **Fixed critical issue with variable replacement in code snippets**: Variables are now properly excluded from replacement within ``, ``, and `
` elements. This prevents corruption of code content, permissions, and technical examples when applying variables to topics containing code snippets.
- **Improved code integrity protection**: The Apply Variables feature now intelligently filters out code snippet elements before processing, ensuring that technical content remains unchanged while still applying variables to regular text content.
- **Fixed track changes setting synchronization**: The VariableFileSelector window now properly respects the global track changes setting from the Options window. Previously, the checkbox was hardcoded to "True" and didn't reflect the user's global preference. Now it initializes with the correct global setting and any changes are synchronized back to the global configuration.
- **Enhanced browse button navigation**: Browse buttons in the Apply Variables to Multiple Topics window now start in the appropriate Flare project folders instead of the computer's root directory. Topic browse starts in the Content folder, and variable browse starts in the Project folder, making file selection much more intuitive.
- **New Backup and Restore System**: Added comprehensive file backup functionality that automatically creates backups before any ButtonCommand execution, with up to 5 backups maintained per file.
- **Smart Diff Viewer**: Implemented an intelligent diff algorithm using Longest Common Subsequence (LCS) that accurately detects content changes rather than just position differences. This prevents false "deleted" or "added" entries when content simply moves to different line numbers.
- **Color-Coded Change Detection**: Enhanced diff viewer with visual indicators - green for added lines, red for removed lines, orange for modified lines, and transparent for unchanged lines.
- **Restore Button in Admin Ribbon**: Added a "Restore from Backup" button in the Admin group that allows users to select and restore from available backups.
- **Backup Selection Window**: New XAML-based interface for selecting specific backups to restore, including change summaries and detailed diff viewing capabilities.
- **Automatic Backup Management**: Backups are automatically created in an "AiHelperBackups" folder within the project directory, with automatic cleanup of old backups to maintain the 5-backup limit.
- **Enhanced Variable File Safety**: Added intelligent detection and visual warnings for variable files containing duplicate variable definitions. Variable files with multiple definitions for the same variable are now displayed in red text with warning tooltips, and are automatically unselected by default to prevent conflicts. The first definition of a variable is always used when duplicates exist.
- **Improved Variable Selection Interface**: Streamlined the Apply Variables to Multiple Topics window by removing unnecessary search and browse functionality for variable files, focusing on the core task of selecting which variable sets to apply. Added a clear legend explaining the color coding system for risky vs. safe variable files.
- Fixed a bug where attributes where mistakenly removed from Markdown text containing li > p.
- Settings in the Options window didn't always persist. Fixed now.
## 1.0.25
**New Features**
- Introduces ClassFormattingTransformer to map specified CSS classes on span/div/p elements to Markdown formatting (bold, italic, underline, numbered, bulleted). Updates UI and settings to allow user configuration of class lists. Refactors Markdown conversion logic to apply these mappings when enabled, improving control over formatting preservation during copy/export operations.
- **Include Snippets/Variables** β Options to expand snippet content and variable values in output. Toggle via new commands and checkboxes.
- **Loose Variable Matching** β Case-insensitive variable replacement; treats spaces and non-breaking spaces as equal. Improved options UI and layout.
- **Use Regular HTML Links** β Option to output `` tags instead of MadCap xref elements.
**Technical Updates**
- All related Markdown conversion functions updated to respect new settings.
- All new options persist in the registry.
- UI updated for clarity and usability.
## 1.0.24
- Fixed a bug where the plugin would crash if you tried to apply variables to a variable file.
## 1.0.23
- Fixed a problem with the installer.
## 1.0.22
- Fixed a problem with the installer.
## 1.0.21
- Fixed an broken link in the GUI.
## 1.0.20
- Fixed a bug where the free trial would not automaticall activate.
## 1.0.19
- Fixed a bug where the license would reset every Monday.
## 1.0.18
- Fixed a bug where snippets would not convert correctly in some cases.
- Added support for nested snippets.
- Xrefs are now converted to markdown links.
## 1.0.17
- Performance optimizations.
## 1.0.16
- Fixed a bug where Markdown links would accidentally be converted to MadCap:keyword.
## 1.0.15
- Fixed a bug where all variables would not be applied if the texts appeared in the same text node.
## 1.0.14
- Fixed a bug where the plugin would crash if you had a partial text selection with a variable in it.
- When adding files using the Search and Compile window, existing files are now kept when you trigger a new search.
- When searching for files, variables are now parsed run-time so that you can search variables as well.
- Added "Split by H1" as an option when splitting topics.
## 1.0.13
- Fixed a bug related to replacing variables.
## 1.0.12
- Fixed a bug related to XHTML pasting.
## 1.0.11
- Fixed a bug related to selection.
## 1.0.10
- Fixed a bug that was causing the replace and insert commands to fail.
## 1.0.9
- Bug fixes.
## 1.0.8
- Added "clear all" and "select all" to the Apply Variables window.
- You can now apply variables to multiple files at the same time.
- You can now copy the underlying XHTML of a topic or a selection, and either insert or replace XHTML into your topics again.
---
## AI Helper Plugin
## AI Helper Tab
The main ribbon tab for your AI-assisted workflow, organized from preparing content for AI to importing AI results back into Flare.
### From Flare β AI
Export and prepare Flare content for use with AI tools:
- **Copy Topic (MD)**: Converts an entire Flare topic to markdown format, preserving all content structure
- **Copy Selection (MD)**: Converts only the selected portion of your content to markdown format
- **Copy Topic (XHTML)**: Copies the entire topic as XHTML
- **Copy Selection (XHTML)**: Copies the selected content as XHTML
- **Search & Compile**: Opens the Search and Compile interface where you can:
- Search for specific topics across your project
- Select multiple topics to include
- Combine selected topics into a single markdown document
- Create comprehensive content collections for AI analysis
- **Generate Prompt**: Select a template to generate a prompt from your saved templates
- **Edit Templates**: Open the template editor to manage and customize templates for common AI interactions
### From AI β Flare
Import AI-generated content back into Flare:
- **Insert After Selection**: Takes AI-generated markdown content (or XHTML) and inserts it after your current cursor position or selection, automatically converting it to properly formatted Flare content
- **Replace Selection**: Replaces your selected content with AI-generated markdown (or XHTML), maintaining proper Flare formatting and structure
- **Create Topic**: Creates a new topic from markdown content in your clipboard, automatically converting it to properly formatted Flare content
- **Create Snippet**: Creates a snippet specifically from clipboard markdown content
- **Replace Topic**: Replaces the entire content of the current topic with XHTML or Markdown from your clipboard. Automatically detects the clipboard format and handles conversion. Preserves topic metadata and head element while replacing body content. Creates automatic backup before replacing.
- **Split by H1**: Divides the content based on first-level headings only
- **Split by H2**: Divides the content based on first and second-level headings
- **Split by H3**: Divides the content based on first through third-level headings
- **Split by H4**: Divides the content based on first through fourth-level headings
All split commands generate file names following MadCap best practices: hyphens between words, title case, removal of minor words (a, the, in, on, etc.), and include a progress bar showing real-time splitting progress.
### Cleanup
Normalize and prepare imported content for publishing:
- **Apply Variables**: Applies variables to the current topic based on the existing variable files in the project
- **Apply Variables to Multiple Topics**: Search for and apply variables to multiple topics at once
- **Apply Snippets**: Automatically finds and replaces matching text content with snippet references. Only displays snippets that match content in the current topic. Features include automatic content matching with configurable options (loose matching, Levenshtein distance), live snippet preview showing full XML content, smart relative path calculation for proper snippet references, and track changes support
- **Create Variable File**: Create a MadCap variable file from a comma-separated list. Uses clipboard if available, otherwise shows an input dialog where you can enter variables manually (one per line, comma-separated, or as markdown bullet list)
- **Replace Tags**: Easily replace tags in your content
### AI Assistants
Quick access to popular AI platforms:
- **ChatGPT**: Opens OpenAI's ChatGPT in your browser
- **Claude**: Opens Anthropic's Claude in your browser
- **Copilot**: Opens Microsoft Copilot in your browser
- **Grok**: Opens X's Grok in your browser
- **Gemini**: Opens Google Gemini in your browser
- **Perplexity**: Opens Perplexity AI in your browser
### Utilities
General-purpose tools for working within Flare:
- **Markdown Editor**: Opens a powerful markdown editor with live HTML preview, syntax highlighting, and formatting buttons (H1-H3, Bold, Italic, Links, Lists, Tables, Code). Features dual-pane interface with side-by-side markdown editing and real-time preview. Supports saving as .md, .htm, or .flsnp format with automatic conversion to Flare XHTML
- **Options**: Open the plugin options window to configure all settings
- **Restore from Backup**: Restore the current file from a previous backup
### Admin
Administrative and support tools:
- **Documentation**: Access the plugin documentation
- **Report a Bug**: Send a bug report via email
- **Suggest a new Feature**: Submit feature requests
- **About**: Information about the plugin and ImprovementSoft
- **Contact Mattias**: Direct email contact with the developer
- **Get the Latest Version**: Check for and download plugin updates (only shown when update is available)
## LLMS.txt Tools Tab
A separate tab dedicated to AI data management and content preparation for large language models.
### LLMS.txt Tools
- **Add Description**: Add or edit the description meta tag for the current topic, which is automatically extracted during llms.txt generation
- **Generate LLMS.txt**: Generate markdown files and llms.txt from your Flare build output, converting HTML to clean MD format with TOC structure
- **Generate Markdown Target**: Create a clean, standalone Markdown documentation package:
- Generates MD files from HTML build output
- Parses TOC structure and creates llms.txt
- Copies only essential files (MD, images, resources) to a separate target folder
- Automatically removes Skins folder and empty directories
- Perfect for publishing pure Markdown documentation or LLM-ready content
### Utilities & Admin
The Utilities and Admin groups are also available on this tab for convenient access to settings and support tools while working with LLMS.txt features.
## Configuration Options
The plugin includes comprehensive settings accessible through the Options window:
### General Settings
- **Track Changes**: Control basic plugin behavior
### Flare to Markdown Settings
- **Enable classβformat mapping**: Map specific CSS classes to bold/italic/underline or list formatting
- **Include Snippet Content**: Expand and include snippet content in copied text
- **Include Variable Text**: Replace variable references with their actual values
- **Custom class mappings**: Configure which CSS classes map to bold, italic, underline, numbered lists, and bulleted lists
### Markdown to Flare Settings
- **Enable Markdownβclass mapping**: Convert Markdown elements to Flare elements with CSS classes
- **Custom element mappings**: Configure how bold, italic, headings, lists, and code elements are converted
- **Add bookmark links to headings**: Control whether bookmark anchor tags are added to headings during Markdown conversion. When disabled, only unreferenced bookmarks are removed, preserving internal document links
### Link Settings
- **Use Regular HTML Links**: Convert links to regular `` tags instead of MadCap xref elements
### Variables Settings
- **Loose Variable Matching**: Ignore case and treat spaces and non-breaking spaces as equivalent when matching variables
### Snippets Settings
- **Loose Snippet Matching**: Ignore case and normalize spaces when matching snippet content
- **Use Levenshtein Distance Matching**: Enable fuzzy matching for snippets that are similar but not exact matches
- **Default Levenshtein Threshold**: Maximum edit distance allowed for fuzzy matching (lower = stricter matching)
### LLMS.txt Settings
- **Auto-append .md to filenames**: Choose between `file.htm.md` or `file.md` format for generated Markdown files
- **Glossary Term Handling**: Control how glossary term popups are processed when generating Markdown. Options: Remove definitions (default), Keep inline, or Append as glossary section at end of file
---
## Automator Plugin
With the Automator plugin, you can build your very own MadCap Flare plugin to automate the things you do over and over again, saving you both time and energy in the process.
To learn how SimCorp uses the Automator plugin see the MadCap webinar: [The Power of MadCap Flare Supports Large-scale Documentation and Fuels SimCorp's Continuous Delivery of 450k+ Help Topics](https://www.madcapsoftware.com/webinars/the-power-of-madcap-flare-supports-large-scale-documentation-and-fuels-simcorps-continuous-delivery-of-450k-help-topics/)
## Release Notes
### 2025-12-15
**Execution History & Logging**
- All button executions are logged with timestamps, arguments, and success status
- View execution history via the new "View history" button in the Automator ribbon
- Daily log files stored in `%AppData%\Improvementsoft\Automator-Logs\`
- Filter by date to review past executions
**Share Buttons via Base64**
- Export any button configuration as a Base64 string (includes Tab, Group, and all settings)
- Import buttons by pasting a Base64 string
- Share button configurations with team members or across projects
- Access via "Copy selected as Base64" and "Import button (Base64)" in Settings
**Multiple XML Settings Files**
- Automatically loads all `.xml` files from the settings folder
- Organize buttons across multiple files (e.g., `Automator-Settings.xml`, `Automator-Team.xml`)
- Settings are merged automatically on plugin load
- Main settings file loads first, then additional files alphabetically
**Remote Settings Support** (Backend Ready)
- Infrastructure added for automatic import from URLs and network shares
- Settings can be downloaded from HTTP/HTTPS URLs or copied from UNC network paths
- Cached locally for offline use
- UI for managing remote sources will be available in a future update
### Improvements
- Better error handling during button execution
- Execution duration tracking in logs
- Improved settings file organization and management
### Technical Details
- Log files use JSON Lines format (one entry per line)
- Base64 export includes Tab, Group, Label, Path, Arguments, Icon, and Tooltip
- Multi-file loading maintains backward compatibility with existing single-file setups
---
| Date | What's New? |
|------------|-------------|
| 2020-05-06 | Updated installer so that it works with Flare 2020. |
| 2020-04-12 | Corrected a bug where the [%root%] variable returned the root path with "\\" at the end - causing python scripts to fail. |
| 2019-05-31 | First release. |
## Build Your First Plugin Using the Automator
To create a plugin button that opens the current topic in Notepad, follow these steps:
1. Click **Set up automations** on the **Automator** tab. The **Automator Settings** window appears.
2. Set **Tab** to **My Plugin**.
3. Set **Group** to **Notepad**.
4. Set **Path** to **C:\windows\notepad.exe**
5. Set **Arguments** to **"[%topic%]"**
6. Set **Icon** to **face**.
7. Set **Label** to **Open in Notepad**.
8. Set **Tool tip** to **Opens the current file in Notepad**.
9. Click **Save**.
10. **Close** the settings window and restart Flare.
Your Flare ribbon now has a tab called **My Plugin**... go check it out!
## Examples
The table provides a few examples of automations you can create. For more complex workflows, I recommend you use .BAT files, Power Shell scripts, or even Python scripts.
| Tab | Group | Path | Arguments | Icon | Label | Tool Tip |
|-----------|------------------|----------------------------------------------------------|---------------------------------------------------------------------------------|-----------------|----------------------|----------|
| My Plugin | Browser shortcuts| https://www.google.com | | stars | Google | Opens google.com in your browser. |
| My Plugin | Text editors | C:\...\Notepad++.exe | "[%topic%]" | code | Open in Notepad++ | Opens the current topic (or other file) in Notepad++ for editing. |
| My Plugin | MadBuild | C:\...\Flare.app\madbuild.exe | -project "C:\\...\SampleProject.flprj" -batch "NewBatchTarget" | build | Build batch target | Builds the target using madbuild.exe. |
| My Plugin | Pandoc | C:\...\pandoc.exe | "[%topic%]" -o "[%desktop%]\REPLACE([%topicFileName%], .htm, .docx)" | import_export | Convert to Word | Converts the current topic to a Word document and saves it on your desktop. |
| My Plugin | Pandoc | C:\...\pandoc.exe | "[%topic%]" -o "[%desktop%]\INPUT(Enter file name)" | import_export | Convert to any format| Converts the current topic to another format, depending on the file name suffix, e.g. .md or .docx. |
## Argument Variables
To integrate your automations with Flare, you can use special argument variables to your scripts or executable files.
**NOTE**: To ensure that spaces in file paths are handled properly, you should wrap the variables in double quotation marks, e.g. "[%topic%]".
| Variable | Value |
|-------------------|-------|
| [%topic%] | The path to the currently open (and in focus) topic (or other file). For example: c:\My projects\Mattias\Content\Topic A.htm |
| [%root%] | The path to the root folder of the Flare project (the folder with the .flprj file). For example: c:\My projects\Mattias\Content\Topic A.htm |
| [%topicFileName%] | The file name of the currently open topic. For example: Topic A.htm |
| [%content%] | The path to the /Content/ folder, for example:
c:\My projects\Mattias\Content\ |
| [%flprj%] | The path to the Flare project (.flprj) file. |
| [%desktop%] | The path to your desktop folder. For example: C:\users\mattias\desktop |
## Custom Argument Functions
To make your automations even more powerful - you can use the following functions in the **Arguments** field.
::: Note
To ensure that spaces in file paths are handled properly, you should wrap the functions in double quotation marks, e.g. "INFILE()".
:::
| Function | Description |
|-------------------------------------------|-------------|
| REPLACE(This is my text, text, dog) | Replaces the word "text" with "dog" in the string "This is my text" - resulting in a string that reads "This is my dog". |
| INPUT(This is a title) | Prompts you to enter text or value when you run your automation. For example, INPUT(Please enter your name) would ask you for your name, and then replace the entire "INPUT(This is a title)" element with your name. |
| SELECT(Option 1, Option 2, Option 3) | Asks you to select an option from a list item box. |
| INFILE() | Asks you to select a file from your computer. |
| MULTISELECT(Option 1, Option 2, Option 3) | Asks you to select one or more options. The result is a list separated by ";", for example: "Option 1;Option 2; Option 3". |
| OUTFILE() | Asks you to select a save-file. |
| FOLDER() | Asks you to select a folder. |
| CLIPBOARD() | Gets the content from your clipboard. |
| SELECTION() | Gets the selected text from your topic (if any). |
---
## Plugin Documentation
Select a plugin to view its documentation, guides, and release notes.
## Plugins
- **[AI Helper Plugin](/docs/AI%20Helper%20Plugin/)** β AI acceleration for structured documentation in MadCap Flare
- **[Kaizen Plugin](/docs/Kaizen%20Plugin/)** β 30+ free productivity utilities for MadCap Flare
- **[Mad Quality Plugin II](/docs/Mad%20Quality%20Plugin%20II/)** β Automated style guide enforcement and QA
- **[Markdown Plugin II](/docs/Markdown%20Plugin%20II/)** β Bridge docs-as-code and Flare with Markdown import/export
- **[Style Stack Plugin](/docs/Style%20Stack%20Plugin/)** β Multi-class CSS composition in MadCap Flare
- **[Kaizen Reviewer](/docs/Kaizen%20Reviewer/)** β Review workflow tooling for MadCap Flare
- **[Word Import Plugin](/docs/Word%20Import%20Plugin/)** β Import Word documents into MadCap Flare
- **[Automator Plugin](/docs/Automator%20Plugin/)** β Batch automation for MadCap Flare
---
## Export Target Condition Data
Creates a spreadsheet with the conditions explicitly set for each target, for example:
| Target | Folder | Target type | Default.ScreenOnly | Default.PrintOnly |
| ---------------- | ---------------------------------------------------------------------------------------------- | ----------- | ------------------ | ----------------- |
| CLEAN | C:\\Users\\...\\Project\\Targets | WebHelp2 | | |
| HTML5 | C:\\Users\\...\\Project\\Targets | WebHelp2 | X | |
| KaizenTarget | C:\\Users\\...\\Project\\Targets | PDF | | |
| KaizenWordTarget | C:\\Users\\...\\Project\\Targets | MsWord | | |
| PDF | C:\\Users\\...\\Project\\Targets | PDF | | X |
| Word 1 | C:\\Users\\...\\Project\\Targets | MsWord | | |
---
## Release Notes
- **Version 2.2.50** (2026-07-27)
- **Bookmark & Create TOC** now transfers each heading's condition tags onto the matching generated TOC entry, so entries are included or excluded by the same target rules as the heading itself β no more TOC links pointing at headings that are conditioned out of a build (works for both the single-topic and multi-topic versions)
- **Flare Diagnosis:** links whose target is a Flare variable/expression (e.g. `[%=Variables.PDF_Link%]`) are no longer reported as broken cross-references or broken image/snippet references β those resolve at build time and can't be checked against files on disk
- **Version 2.2.49** (2026-07-22)
- Added **Flare Diagnosis** (Cleanup β‘ tab β Project Analysis): one-click health check of your Flare project β runs 40+ deterministic rules across project integrity, links & references, reuse hygiene, style & markup, content hygiene, assets, and build configuration
- The diagnosis report opens with a plain-language verdict, a "what this is costing you" summary, and a prioritized checklist where each finding expands to the list of affected files. Everything runs locally β no data leaves your machine
- Flare Diagnosis reports can be saved as a standalone HTML file to share with your team
- Quick Word/PDF/HTML now shows a friendly "close the document and try again" message when the generated output file is open in another program, instead of raising an error report
- Kanban Board: the *Attach files* dialog now keeps your selection in a visible basket that survives searching and filtering, so you can collect files across multiple searches before attaching them all at once
- Kanban Board: card faces now show the names of attached files, with full paths in the tooltip
- Remove Local Styling now also removes a style attribute on the topic's root element
- **Version 2.2.48** (2026-05-26)
- Added new dedicated **Kanban β‘** ribbon tab for in-project work management
- Added **Kanban Board** button: plan and track Flare work as cards stored under `.kanban/` in the project root, with columns, types, checklists, file attachments, and a second tab that surfaces `madcap:annotation` notes grouped by their UPPERCASE prefix
- Added **Add Topic to Card** button: package the currently open topic onto a Kanban card in one click β attach to an existing card or create a new one pre-loaded with the topic. Useful when collecting the set of topics that need to be touched for a particular job
- Plugin Settings now includes a *Kanban Tab:* section for hiding the Kanban group
- **Version 2.2.47** (2026-05-06)
- Fixed ObjectDisposedException ('CatapultContentExplorer') reported on shutdown by no longer disposing Flare's IHost (the plugin does not own it)
- Extended Flare-internal exception filter to also swallow ObjectDisposedExceptions raised by Catapult* / ContentExplorer / ProjectExplorer types, so Flare's own teardown bugs no longer surface as plugin error dialogs
- **Version 2.2.46** (2026-04-22)
- TODO Notes now also scans .html files for annotations
- **Version 2.2.45** (2026-04-15)
- Added Snippet Picker: search and insert snippets by name or content with live preview, Launchy-style keyboard navigation (type to search, arrow keys to browse, Enter to insert)
- Added Variable Picker: separate ribbon button to search and insert variables by name or value
- Snippets and variables now insert at the actual cursor position within text, splitting the text node correctly
- Empty elements are replaced when inserting a block snippet or inline content into them
- Inserting snippets and variables no longer causes the topic to close and reopen
- Custom Block/Inline dialog when inserting single-block snippets, with clear button labels
- **Version 2.2.44** (2026-04-02)
- Fixed false error reports caused by Flare internal exceptions (ObjectDisposedException on CatapultFlareFullDependencyMdiEditor) reaching the AppDomain handler, which lacked the Flare exception filtering already present on the UI thread handler
- **Version 2.2.43** (2026-03-25)
- Fixed Data Import (Excel) becoming unresponsive when the file name pattern contains multiple placeholders (e.g., `[[ID]] [[Guideline]].flsnp`)
- **Version 2.2.42** (2026-03-25)
- Fixed QuickWord/QuickPDF/QuickHTML TFS checkout crash by bypassing TFS checkout for plugin temp files (KaizenTempToc, KaizenTargets) and directly clearing the read-only attribute instead
- Fixed MissingMethodException (`Url..ctor(String)`) on older Flare versions by using cross-version compatible `Url.ReplaceSource` API
- **Version 2.2.41** (2026-03-24)
- Fixed QuickWord/QuickPDF/QuickHTML crash when checking out files from TFS source control, caused by an invalid leading backslash in the file path passed to the TFS provider
- **Version 2.2.40** (2026-03-09)
- Fixed crash (AggregateException) during XML validation caused by a threading race condition when updating the progress dialog
- Validation progress updates are now guarded against form disposal, preventing unhandled exceptions when validation completes quickly
- **Version 2.2.39** (2026-02-25)
- Fixed Sort TOC to handle namespace-aware XML when resolving linked titles from topic files
- Fixed Sort TOC crash when TOC entries have null or empty titles
- Improved path handling in Sort TOC using Path.Combine instead of string concatenation
- Sort TOC now gracefully falls back to filename when topic files cannot be loaded
- **Version 2.2.38** (2026-01-27)
- Enhanced To Do Notes with configurable keyword filtering (TODO, FIXME, NOTE, REVIEW, HACK, and custom keywords)
- To Do Notes now shows the annotated text and surrounding context for each item
- Added source filtering to include/exclude TOC entries from To Do list
- Added search functionality and keyword color-coding to To Do Notes
- Settings are now saved per-user and restored when reopening the form
- **Version 2.2.37** (2026-01-27)
- Added new "Excel to Auto Suggestions" feature on the Import tab that converts an Excel file to a Flare Auto Suggestions file (.fltbx)
- Simply create an Excel file with phrases/sentences in the first column and import them as auto suggestions for faster content authoring
- **Version 2.2.36** (2026-01-20)
- Fixed exception filtering for non-English Windows installations where localized stack traces use translated keywords (e.g., "ved" in Norwegian instead of "at").
- **Version 2.2.35** (2025-12-12)
- Fixed B3.* exception filtering to check TargetSite namespace when StackTrace is not yet populated.
- **Version 2.2.34** (2025-11-24)
- Enhanced error filtering to ignore all MadCap Flare internal exceptions (B3.* namespace) instead of only specific B3 libraries.
- **Version 2.2.33** (2025-11-07)
- Misc bug fixes related to error catching.
- **Version 2.2.32**
- Misc bug fixes.
- **Version 2.2.31** (2025-10-20)
- Added new "Snippet Usage Report" feature that analyzes all snippets in a project
- Report shows usage count for each snippet with sortable columns
- Includes progress dialog with real-time updates and cancellation support
- Optimized performance: reads each file only once instead of once per snippet (up to 500x faster for large projects)
- Smart double-click behavior: opens all files for multi-use snippets with user confirmation
- Helps identify unused or rarely-used snippets for cleanup and maintenance
- **Version 2.2.30** (2025-10-15)
- Fixed QuickWord timing bug where builds succeeded but files older than 20 seconds were rejected - increased threshold to 60 seconds and added detailed diagnostics
- Plugin now filters out Flare's internal B3 library errors, passing them to Flare's error handling instead of showing KaizenPlugin error reports
- Improved error messages when output files are found but too old, with suggestions to delete output folder
- **Version 2.2.29** (2025-10-10)
- Apply Links to TOC now excludes PDFs, preserving manually entered PDF titles instead of overwriting them with filenames
- Fixed QuickWord to properly find .docx files (pattern changed from *.doc to *.doc*)
- Fixed misleading error messages - now says "Try closing the output file" instead of "PDF" for all document types
- Fixed log parser to extract any file type from build logs, not just PDFs
- Error reports now include last 10 lines from MadCap build log (.mclog) for better diagnostics
- **Version 2.2.28** (2025-10-04)
- Added new Settings feature allowing users to customize which groups are visible within each tab
- QuickPDF, Quick Word, and Quick HTML now work for snippets.
- **Version 2.2.27** (2025-09-25)
- Quick PDF and Quick Word and Tag Replacer, and Accept/Reject All Changes now works with Flare 2025 r2
- Better error logging
- **Version 2.2.26** (2025-08-26)
- Fixed Advanced Tag Replacer form appearing as topmost window by explicitly setting TopMost property to false
- This ensures the form doesn't stay on top of other windows during use
- **Version 2.2.25** (2025-08-05)
- Fixed ZIP backup compatibility with Windows Explorer by implementing a new manifest-based format while maintaining backward compatibility with legacy ZIP files
- Added user-friendly read-only file handling during restoration
- Fixed "Out of Memory" error when processing SVG files in the Set Alt Text dialog
- Added proper error handling and UI improvements for better user experience
- Added "Export Glossary to Excel" feature that extracts glossary terms, definitions, and links from .flglo files into Excel spreadsheets
- Added enhanced XML validation options allowing users to validate XML for specific folders, TOC files, individual topics, or the entire project, with improved TOC relative path resolution
- **Version 2.2.21-24** (2025-05-23)
- Misc bug fixes, and an update to the installer
- **Version 2.2.20** (2024-02-21)
- Fixed a bug related to Data Import, where if the file name field had a "/" - the imported file would only contain the part after the slash
- **Version 2.2.19** (2023-12-11)
- Fixed a bug related to Micro Content Import
- **Version 2.2.15** (2023-09-26)
- Improved memory management in the ALT texts feature
- **Version 2.2.14** (2023-07-31)
- Fixed bug in Tag Replacer
- You can now validate XML in specific folders
- Various bug fixes
- **Version 2.2.13** (2023-06-21)
- Support for multiple file extensions in the Fast File Search
- New button to close all topics and snippets
- **Version 2.2.12** (2023-06-14)
- When accepting all changes in a project, non-significant line breaks would be removed. Now they are not
- **Version 2.2.11** (2023-05-30)
- Fixed a bug where the tabs would duplicate in Flare
- The Markdown Plugin I is no longer supported
- The Kaizen Script functions are no longer supported
- **Version 2.2.8** (2023-05-08)
- Installer updated for Flare 2023
- **Version 2.2.7** (2023-02-15)
- The Quick Word feature now uses .docx instead of .doc
- **Version 2.2.6** (2022-11-11)
- If the tag replacer comes across a topic without a body tag, it will now provide a better error message
- Correction related to spaces in the accept/reject all changes
- **Version 2.2.5** (2022-10-19)
- Leading and trailing spaces are now properly handled when accepting/rejecting all changes in a project
- **Version 2.2.4** (2022-08-18)
- The "bookmark topic and create TOC" functions no longer ignore sup/sub tags
- **Version 2.2.3** (2022-05-31)
- The QuickWord/PDF/HTML doesn't support non-default output files or folders: added error message
- **Version 2.2.2** (2022-02-26)
- Fix to the problem that caused the Quick PDF/Word to sometimes fail in Flare 2021r3
- Fix to the problem where condition export would not work in Flare 2021r3
- Build a "Quick HTML" target for a CleanXHTML version of the topic you have open
- **Version 2.2.1** (2021-12-13)
- Updated the Kaizenscript functionality so that you can re-install a script without deleting the existing DLL file first
- **Version 2.2.0** (2021-11-02)
- Redesigned KaizenScript functionality for faster and easier deployment of custom add-ons
- Bug fix related to the MadCap prefix in the tag replacer destination field
- **Version 2.1.4** (2021-10-20)
- Fixed a bug in the TO DO notes function affecting the Link Viewer
- Removed the old Kaizen Script functionality
- PDFs created by the Quick PDF feature now get a unique name
- The condition tag export now supports condition tags with special characters
- **Version 2.1.3** (2021-08-03)
- The fast file search normal search is now case insensitive
- **Version 2.1.2** (2021-07-23)
- Bug fixes
- **Version 2.1.1** (2021-07-09)
- Fixed bugs related to replacing empty tags and target condition use export
- **Version 2.1.0** (2021-05-11)
- Optimized the release flow
- **Version 2.0.7800.28098** (2021-05-11)
- The installer now has silent mode enabled
- **Version 2.0.7786.20438** (2021-04-26)
- Corrected bug related to creating a TOC and bookmarking the topic
- Bug that would sometimes remove text when all changes were accepted
- **Version 2.0** (2021-04-09)
- Added button to open a random topic or snippet
- **Version 2.0.7746.14208** (2021-03-17)
- Clarified MD1 vs MD2 icons
- **Version 2.0.7745.39186** (2021-03-16)
- Updated help call URL
- **Version 2.0.7738.17309** (2021-03-09)
- Fixed a bug that causes the topic creator functionality to crash in some cases
- Added small icons to buttons
- **Version 2.0.7735.36061** (2021-03-06)
- New color icons that work better for dark mode
- **Version 2.0.7713.20478** (2021-02-12)
- Various changes for the release of the separate docs for Markdown II
- **Version 2.0.7657.23742** (2020-12-18)
- Corrected a bug when accepting all tracked changes in a project
- **Version 2.0.7653.21440** (2020-12-14)
- Various bug fixes for the Markdown plugin
- Fixes for the Sort TOC function and the Fast File Search function
- The Validate XML function now supports all types of Flare files
- **Version 2.0.7592.23195** (2020-10-14)
- Bug fixes and added config file to support differences in table import settings
- **Version 2.0.7577.23994** (2020-09-29)
- Bug fixes related to the Markdown plugin license key
- **Version 2.0.7565.33411** (2020-09-17)
- Bug fixes related to Markdown table import and the **Apply Links to TOC** function
- **Version 1.0.7433.19185** (2020-05-18)
- Bug fixes related to To Do notes form buttons and Markdown table import
- **Version 1.0.7433.18756** (2020-05-08)
- Bug fixes for Advanced Tag Replacer, Markdown export, and Tag replacer
- **Version 1.0** (2020-05-06)
- Advanced Tag Replacer
- Installation helper for KaizenScripts
- Feature to convert Excel sheets to HTML tables
- Google Calendar or Outlook reminders for topic review
- Updated installer for Flare 2020
- Bug fixes
- **Version 1.0** (2020-03-07)
- Micro content import from Excel
- Bug fixes
- **Version 1.0.7202.23531** (2019-09-20)
- Bug fixes in relation to the updated Markdown plugin
- **Version 1.0** (2019-09-06)
- Faster Tag Replacer
- GUI changes
- Batch setting for alt image texts
- Statistics feature
- **Version 1.0** (2019-07-31)
- Updates to the Markdown plugin
- Bug fixes
- **Version 1.0** (2019-05-31)
- Updated link to online help
- Internal improvements to the Quick PDF functionality
- **Version 1.0** (2019-04-18)
- Updated Accept/Reject all changes-functionality
---
## Kaizen Plugin - Complete Feature Guide
Welcome to the comprehensive guide for the Kaizen Plugin for MadCap Flare. This document provides an overview of all features organized by tab and functional area.
## About the Kaizen Plugin
The Kaizen Plugin is a productivity enhancement tool for MadCap Flare that adds powerful features for content management, automation, and workflow optimization. It's completely free to use and continuously developed.
For support or feature requests, contact: mattias@improvementsoft.com
## Feature Organization
The plugin organizes features into five main tabs:
### 1. Kaizen Plugin Tab β‘
**File Group**
- [Copy Path to Clipboard](11%20Copy%20Path%20to%20Clipboard.md) - Copy the current topic's path
- [Fast File Search](12%20Fast%20File%20Search.md) - Quick file search with wildcards and REGEX
- [Open Random Topic or Snippet](13%20Open%20Random%20Topic%20or%20Snippet.md) - Serendipitous content discovery
- [Close Topics and Snippets](14%20Close%20Topics%20and%20Snippets.md) - Clean up your workspace
**Topic Splitter Group**
- [Split by H1-H5](4%20Split%20a%20topic%20and%20create%20a%20TOC.md) - Split topics by heading level and create TOC
**TOC Tools Group**
- [Bookmark & Create TOC](15%20Bookmark%20and%20Create%20TOC.md) - Add bookmarks and generate in-topic TOC
- [Apply Links to TOC](16%20Apply%20Links%20to%20TOC.md) - Apply System.LinkedTitle variables
- [Sort TOC Alphabetically](17%20Sort%20TOC%20Alphabetically.md) - Sort TOC entries
**Information Architecture Group**
- [Create Word Cloud](7%20Create%20Wordcloud.md) - Visualize most-used terms
- [Farm Glossary Terms](8%20Farm%20Glossary%20Terms%20from%20your%20project.md) - Extract glossary candidates
**Backup Group**
- [Backup and Restore](18%20Backup%20and%20Restore.md) - Protect and recover your work
### 2. Cleanup Tab β‘
**Styling Group**
- [Remove Local Styling](19%20Remove%20Local%20Styling.md) - Strip inline styles from topics
**Tracked Changes Group**
- [Track Changes Tools](20%20Track%20Changes%20Tools.md) - Accept/reject all changes
**Tag Replacer Group**
- [Replace Tags in Topic](1%20Replace%20tags%20in%20a%20topic.md) - Replace HTML tags in current topic
- [Replace Tags in Folder](2%20Replace%20tags%20in%20a%20folder.md) - Batch replace tags
- [Advanced Tag Replacer (REGEX)](3%20Replace%20tags%20using%20REGEX.md) - REGEX-based tag replacement
**Project Analysis Group**
- [Validate XML](21%20Validate%20XML.md) - Check XML integrity across project
- [Export Variable Data](2%20Export%20Variable%20Data.md) - Export variable usage to CSV
- [Analyze Condition Use](1%20Analyze%20Condition%20Use.md) - Analyze condition tag patterns
- [Export Target Condition Data](0%20Export%20Target%20Condition%20Data.md) - Export target conditions
- [Project Statistics](23%20Project%20Statistics.md) - View tag usage statistics
- [Flare Diagnosis](32%20Flare%20Diagnosis.md) - One-click project health check: 40+ local rules, plain-language verdict, prioritized checklist, HTML report
**Image Tools Group**
- [Set ALT Texts](22%20Set%20ALT%20Texts.md) - Batch set alt text for images
### 3. Import Tab β‘
**Micro Content Group**
- [Import Micro Content from Excel](3%20Import%20micro%20content%20from%20Excel.md) - Create .flmco files from spreadsheets
**Markdown Group**
- [Import Markdown File](5%20Import%20a%20Markdown%20file%20to%20Flare.md) - Convert Markdown to Flare topics
**Glossary Group**
- [Import and Export Glossary](24%20Import%20and%20Export%20Glossary.md) - Work with glossaries in Excel
**Topic Creator Group**
- [Create Topics from CSV or Excel](10%20Creating%20topics%20from%20CSV%20or%20Excel%20file.md) - Generate topics from data
**Excel to Table Group**
- [Import Excel to Table](25%20Import%20Excel%20to%20Table.md) - Convert Excel data to HTML tables
**Auto Suggestions Group**
- [Excel to Auto Suggestions](30%20Excel%20to%20Auto%20Suggestions.md) - Create Auto Suggestions file from Excel
### 4. Productivity Tab β‘
**To Do & Reminders Group**
- [Add To-Do Notes](9%20Add%20a%20To-Do%20note%20to%20a%20topic.md) - Track tasks with annotations
- [Calendar Reminders](26%20Calendar%20Reminders.md) - Create Google/Outlook reminders
**Review Group**
- [Quick Documents](27%20Quick%20Documents.md) - Generate quick PDF, Word, or HTML output
**Snippets Group**
- [Snippet Usage Report](29%20Snippet%20Usage%20Report.md) - Analyze snippet usage and find unused snippets
### 5. Kanban Tab β‘
**Kanban Group**
- [Kanban Board](31%20Kanban%20Board.md) - In-project Kanban board stored as Markdown under `.kanban/`, with columns, types, checklists, file attachments, and an annotation-driven board
- [Add Topic to Card](31%20Kanban%20Board.md) - Package the currently open topic onto a Kanban card in one click
### Configuration
**Plugin Settings**
- [Plugin Settings](28%20Plugin%20Settings.md) - Customize visible tabs, groups, and buttons
## Getting Started
1. Install the Kaizen Plugin from www.improvementsoft.com
2. Open MadCap Flare
3. Look for the "Kaizen Plugin β‘" tabs in the ribbon
4. Click the **Settings** button to customize which features you see
5. Explore the features most relevant to your workflow
## Common Workflows
### Content Cleanup
1. Validate XML across project
2. Remove local styling
3. Replace obsolete tags
4. Accept/reject tracked changes
### Content Creation
1. Import Markdown or Word content
2. Create topics from CSV/Excel data
3. Split large topics by heading level
4. Generate TOC with bookmarks
### Content Maintenance
1. Add To-Do notes for review items
2. Set calendar reminders for updates
3. Use Fast File Search to locate content
4. Generate Quick PDFs for review
### Quality Assurance
1. Run Flare Diagnosis for a full project health check
2. Validate XML markup
3. Check statistics and tag usage
4. Set consistent ALT texts
5. Export condition/variable data for analysis
## Tips for Maximum Productivity
- **Keyboard Shortcuts**: Add frequently-used buttons to the Quick Access Toolbar
- **Settings**: Hide features you don't use to reduce clutter
- **Backups**: Use the backup features before major changes
- **Templates**: Set up template files for Topic Creator features
- **Validation**: Run XML validation regularly to catch issues early
## Support and Updates
- **Help**: Click the **Help!** button on any tab
- **Updates**: Click **Get the NEW version!** when updates are available
- **Bug Reports**: Click **Report a bug** to contact support
- **Website**: www.improvementsoft.com
- **Email**: mattias@improvementsoft.com
## Additional Resources
- [Kaizen Plugin Webinar](https://www.madcapsoftware.com/webinars/how-to-increase-productivity-madcap-flare-kaizen-plugin/)
- [Release Notes](0%20Kaizen%20Plugin%20Release%20Notes.md)
- [ImprovementSoft Blog](https://www.improvementsoft.com/blog)
## Related Products
- **Mad Quality Plugin** - Advanced quality checking and style guide enforcement
- **AI Helper Plugin** - AI-powered content assistance with intelligent formatting
- **Content Migration Services** - Professional migration from any source to Flare
---
*The Kaizen Plugin is developed by Mattias Sander @ Sander Improvement Software AB*
---
## Analyze Condition Use
Creates a spreadsheet with the conditions used by all files linked directly and indirectly from the target file, for example:
| Target | Folder | Default.Mobile | Default.PrintOnly | Default.Tablet |
| ---------------- | ---------------------------------------------------------------------------------------------- | -------------- | ----------------- | -------------- |
| CLEAN | C:\\Users\...\\Project\\Targets | X | X | X |
| HTML5 | C:\\Users\\...\\Project\\Targets | X | X | X |
| KaizenTarget | C:\\Users\\...\\Project\\Targets | | | |
| KaizenWordTarget | C:\\Users\\...\\Project\\Targets | | | |
| PDF | C:\\Users\\...\\Project\\Targets | | | |
| Word 1 | C:\\Users\\...\\Project\\Targets | X | X | X |
---
## Replace tags in a topic
You can only replace tags based on its class attribute, all other attributes will remain the same. For example, if you select to replace
```
```
with
```
```
any b-element with the class element set to "Apples" will be replaced, but will retain its other attributes. For example,
```
```
would become
```
```
1. Click **Replace tags in topic**.
2. Select the tag you want to replace.
3. Select the tag you'd like to use instead.
4. Select the approriate setting
- To replace one tag with another, select **Replace tags**.
- To unbind the tag, and only keep its content, select **Unbind tags**.
- To delete tag tag and its contents, select **Delete tags and content**.
5. Click **Execute**.
If you want to undo the changes before you close the window, click **Undo**.
---
## Creating topics from CSV or Excel files
With the **Topic Creator** tools you can create topics, snippets, or other XML files from a different data sources. This lets you maintain data in, for example, Excel, and then create the topics using a template file.
## Set up a template file
You can set up a template in any valid XML-file, for example, topic files (.htm), snippet files (.flsnp), or even target files (.fltar).
## Set up a template that creates one file per line
1. Create a new file in Flare.
2. Open the file in, e.g. Notepad++.
3. Use the headers from your data file where you want to import the data. For example, if your Excel file has two columns, **Title** and **Description** - you could set up a template like this:
```html
[[Title]]
[[Description]]
```
## Sample CSV data
```csv
Title;Description
Title A;Description A
Title B;Description B
```
## Templates with repeating patterns
If your data is hierarchical, for example like this,
| Title | Data A | Data B | Data C |
| --- | --- | --- | --- |
| Lorem A | Lorem 1 | Lorem 2 | Lorem 3 |
| Lorem A | Lorem 1.1 | Lorem 2.1 | Lorem 3.1 |
| Lorem A | Lorem 1.2 | Lorem 2.2 | Lorem 3.2 |
, you can set up a template with a repeating pattern, where the headers inside the `` are repeated while the other headers stay the same. The example would result in two files each containing a table.
```html
<[[Title]]/h2>
Data A
Data B
Data C
[[Data A]]
[[Data B]]
[[Data C]]
```
## Import data from a CSV file
Note that the CSV file must have a header row.
1. Click **Data Import (CSV)**.
2. Select the path to the CSV file.
3. Select the path to the template file.
4. Select the folder where you want the output files.
5. To overwrite any existing files, select the **Overwrite files** checkbox.
6. To generate the files, click **Execute**.
## Sample CSV data
Title;Description
Title A;Description A
Title B;Description B
## Import data from an Excel file
Note that the Excel file must have a header row.
1. Click **Data Import (Excel)**.
2. Select the path to the Excel file.
3. Select the path to the template file.
4. Select the folder where you want the output files.
5. To overwrite any existing files, select the **Overwrite files** checkbox.
6. To generate the files, click **Execute**.
---
## Copy Path to Clipboard
Quickly copy the path of the current topic to your clipboard for easy reference or sharing with team members.
## To copy the path
1. Open any topic in Flare.
2. Click **Copy Path to Clipboard** in the File group.
3. The full path to the topic is now on your clipboard.
You can paste the path into emails, documentation, or other applications.
---
## Fast File Search
The Fast File Search feature allows you to quickly find and open files using wildcards and REGEX patterns, making it faster than standard Flare search.
## To search for files
1. Click **Fast File Search** in the File group (or press the F key tip).
2. Enter your search term:
- Use wildcards like `*.htm` or `Getting*.htm`
- Use REGEX patterns for advanced searches
3. Select a file from the results.
4. Press Enter or double-click to open the file.
## Tips
- The search is much faster than built-in Flare search for large projects
- Results are displayed instantly as you type
- Searches all content files including topics, snippets, and other XML files
---
## Open a Random Topic or Snippet
Open a random topic or snippet from your project to connect old ideas to new ones or for serendipitous content discovery.
## To open a random file
1. Click **Open a random topic or snippet**.
2. A random topic or snippet file from your project opens in the editor.
This feature is useful for:
- Reviewing forgotten content
- Discovering connections between topics
- Random quality checks
- Breaking out of focused workflow patterns
---
## Close Topics and Snippets
Quickly close all open topic and snippet files while keeping TOC files open, helping you declutter your workspace.
## To close topics and snippets
1. Click **Close topics and snippets** in the File group.
2. All open .htm and .flsnp files are closed.
3. TOC files (.fltoc) remain open.
This is useful when you want to:
- Clean up your workspace
- Focus on TOC structure
- Reduce memory usage in large projects
- Start a new task with a clean slate
---
## Bookmark & Create TOC
Automatically add bookmarks to all headings in a topic and generate a table of contents with bookmarked links. This creates an in-topic navigation system.
## Single File Version
To create bookmarks and TOC for the current topic:
1. Open the topic file.
2. Click **Bookmark & Create TOC** in the TOC Tools group.
3. Bookmarks are added to all headings (h1-h6).
4. A TOC with bookmarked links is created at the top of the topic.
## Multi-File Version
To create bookmarks and TOC across multiple files:
1. Click **Bookmark & Create TOC (Multi)** in the TOC Tools group.
2. Select the topic files you want to process.
3. Bookmarks are added to all headings in each file.
4. A master TOC is generated linking to all bookmarked headings across files.
## Use Cases
- Create single-file manuals with jump navigation
- Generate quick reference guides
- Build long-form content with internal navigation
- Create PDF documents with clickable TOCs
---
## Apply Links to TOC
Automatically apply the `[%=System.LinkedTitle%]` variable to all linked TOC entries, ensuring your TOC always reflects the current topic titles.
## To apply linked titles
1. Open a TOC file (.fltoc).
2. Click **Apply Links to TOC** in the TOC Tools group.
3. The `[%=System.LinkedTitle%]` variable is applied to all entries that link to topics.
## Benefits
- TOC entries automatically update when topic titles change
- Eliminates manual TOC maintenance
- Ensures consistency between topic titles and TOC entries
- Saves time when restructuring content
## Notes
- PDF links are excluded and preserve custom titles you've manually entered
- External links (starting with http) are also excluded
After applying, the TOC will dynamically pull titles from linked topics instead of using static text.
---
## Sort TOC Alphabetically
Sort a TOC file alphabetically, with intelligent handling of the `[%=System.LinkedTitle%]` variable to ensure correct ordering.
## To sort a TOC
1. Open a TOC file (.fltoc).
2. Click **Sort TOC Alphabetically** in the TOC Tools group.
3. The TOC entries are sorted alphabetically.
## Features
- Handles `[%=System.LinkedTitle%]` variables correctly
- Preserves TOC hierarchy and nesting
- Maintains all TOC entry properties and conditions
- Sorts based on actual displayed text, not variable code
This is useful for:
- Reference documentation with alphabetical organization
- API documentation
- Glossaries and term lists
- Any content better served in alphabetical order
---
## Backup and Restore
The Kaizen Plugin provides multiple backup and restore features to protect your work and enable easy recovery.
## Restore Topic
Restore the latest backup of the current topic.
1. Open a topic that you want to restore.
2. Click **Restore Topic** in the Backup group.
3. The topic is restored to its most recent backup version.
## Restore from ZIP
Restore all topics from a previously created ZIP backup file.
1. Click **Restore from ZIP** in the Backup group.
2. Select the ZIP backup file.
3. Choose the destination folder.
4. All topics in the backup are restored.
## Back up File
Create a temporary backup of the current file in the temp directory.
1. Open the file you want to back up.
2. Click **Back up File** in the Backup group.
3. The file is backed up to your temporary directory.
## Tips
- Back ups are created automatically as you work
- ZIP backups are useful for archiving project states
- Individual file backups help with experimental changes
- Always create a backup before major restructuring
---
## Remove Local Styling
Clean up your topics by removing inline style attributes, forcing all styling to come from your CSS stylesheets.
## Remove Styling from Topic
Remove local styling from the current topic:
1. Open a topic file.
2. Click **Remove local styling (topic)** in the Styling group.
3. All inline `style` attributes are removed from elements (except tables).
## Remove Styling from Project
Remove local styling from all topics in the project:
1. Click **Remove local styling (project)** in the Styling group.
2. All inline `style` attributes are removed from all topic files (except tables).
## What Gets Removed
- Inline `style` attributes
- Direct font formatting
- Color and size attributes
- Spacing and margin attributes
## What's Preserved
- Table styling (to maintain table layouts)
- Class attributes
- ID attributes
- All other non-style attributes
## Use Cases
- Clean up content imported from Word or HTML
- Enforce stylesheet-based formatting
- Prepare content for new design systems
- Eliminate inconsistent formatting
---
## Export Variable Data
Creates a spreadsheet with the variable values each target uses.
---
## Replace tags in a folder
You can only replace tags based on its class attribute, all other attributes will remain the same. For example, if you select to replace
```
```
with
```
```
any b-element with the class element set to "Apples" will be replaced, but will retain its other attributes. For example,
```
```
would become
```
```
1. Click **Replace tags in folder**.
2. Select the appropriate folder.
3. To include all sub-folders, select **Include sub-folders**.
4. Select the tag you want to replace.
5. Select the tag you'd like to use instead.
6. Select the approriate setting
- To replace one tag with another, select **Replace tags**.
- To unbind the tag, and only keep its content, select **Unbind tags**.
- To delete tag tag and its contents, select **Delete tags and content**.
7. Click **Execute**. A backup-file is created on your desktop.
If you want to undo the changes before you close the window, click **Undo**.
---
## Track Changes Tools
Quickly accept or reject all tracked changes across your entire project.
## Accept All Changes
Accept all tracked changes in all topics:
1. Click **Accept all changes in project** in the Tracked changes group.
2. All change tracking markup is removed and changes are accepted.
3. Changes are processed across all topic files in the project.
## Reject All Changes
Reject all tracked changes in all topics:
1. Click **Reject all changes in project** in the Tracked changes group.
2. All tracked changes are rejected and original text is restored.
3. Changes are processed across all topic files in the project.
## Use Cases
- Finalize reviewed content
- Reject unwanted batch changes
- Clean up after collaborative editing
- Prepare content for publication
**Warning:** These operations affect all topics in your project. Make sure you have a backup before using these features, or use Flare's built-in version control to review changes before accepting/rejecting.
---
## Validate XML
Validate the XML structure of your topics and snippets to catch malformed markup before it causes build errors.
## Validate XML (Project)
Validate all topics and snippets in the project:
1. Click **Validate XML (Project)** in the Project Analysis group.
2. All .htm and .flsnp files in the project are validated.
3. A report shows any XML errors found.
## Validate XML (Folder)
Validate topics and snippets in a specific folder:
1. Click **Validate XML (Folder)**.
2. Select the folder to validate.
3. All files in the folder (including subfolders) are validated.
4. A report shows any errors found.
## Validate XML (TOC)
Validate all topics linked from a TOC:
1. Open a TOC file.
2. Click **Validate XML (TOC)**.
3. All topics linked from the TOC are validated.
4. A report shows any errors found.
## Validate XML (Topics)
Validate specific topic files:
1. Click **Validate XML (Topics)**.
2. Select the topic files to validate.
3. Selected files are validated.
4. A report shows any errors found.
## Common Issues Detected
- Unclosed tags
- Invalid nesting
- Missing required attributes
- Malformed entities
- Invalid characters
- Encoding problems
Fixing XML errors before building prevents cryptic build failures and improves project stability.
---
## Set ALT Texts
Ensure consistent alt text across your project by setting the same alt text for all instances of the same image.
## To set alt texts
1. Click **Set ALT texts** in the Image Tools group.
2. The tool scans your project for images.
3. For each unique image, enter the alt text you want to use.
4. Click Execute.
5. The alt text is applied to every instance of that image across all topics.
## Benefits
- Ensures consistency - same image always has the same alt text
- Saves time compared to setting alt text manually
- Improves accessibility compliance
- Makes it easier to update alt text globally
## Use Cases
- Accessibility compliance projects
- Consistent branding and descriptions
- Bulk alt text management
- Auditing and fixing missing alt texts
**Tip:** This tool is especially useful after importing content or when you need to standardize alt text across a large project.
---
## Project Statistics
View comprehensive statistics about condition tags and file tags used in your project.
## To view statistics
1. Click **Stats, stat!** in the Project Analysis group.
2. A detailed statistics window opens showing:
- Condition tag usage across files
- File tag distribution
- Tag frequency and patterns
- Files using specific tags
## Information Displayed
- **Condition Tags**: Which condition tags are used and where
- **File Tags**: Distribution of file tags across content
- **Usage Counts**: How many times each tag is used
- **File Lists**: Which files use which tags
## Use Cases
- Audit tag usage before reorganization
- Identify unused or rarely used tags
- Plan condition-based publishing strategies
- Clean up redundant tagging
- Understand project complexity
This data helps you make informed decisions about content organization and build configurations.
---
## Import and Export Glossary
Work with Flare glossaries using Excel spreadsheets for easier editing and collaboration.
## Import a Glossary from Excel
Convert an Excel spreadsheet into a Flare glossary file:
1. Prepare an Excel file with two columns:
- Column A: **Term** (the glossary term)
- Column B: **Definition** (the term definition)
- Optionally add a third column: **Link** (URL or topic link)
2. Include a header row.
3. Click **Import a Glossary From Excel** in the Glossary group.
4. Select your Excel file.
5. Choose the location to save the .flglo file.
6. Click Execute.
### Sample Excel Format
| Term | Definition | Link |
|------|------------|------|
| API | Application Programming Interface | https://example.com/api |
| SDK | Software Development Kit | |
## Export Glossary to Excel
Convert a Flare glossary to Excel format:
1. Click **Export Glossary to Excel** in the Glossary group.
2. Select the .flglo file you want to export.
3. Choose where to save the Excel file.
4. Click Execute.
5. The glossary is exported with Term, Definition, and Link columns.
## Use Cases
- Maintain glossaries in Excel for easier editing
- Collaborate with subject matter experts who prefer Excel
- Bulk edit glossary terms
- Import glossaries from other systems
- Share glossaries with team members who don't use Flare
---
## Import Excel to Table
Convert Excel spreadsheet data into HTML table code that you can paste directly into Flare topics.
## To import a table
1. Prepare your data in Excel.
2. Click **Import Excel to table** in the Excel to Table group.
3. Select the Excel file.
4. Choose the worksheet and range to import.
5. Click Execute.
6. The HTML `` code is copied to your clipboard.
7. Paste the code into your Flare topic.
## Features
- Converts Excel data to clean HTML table markup
- Preserves basic formatting
- Creates proper table structure with ``, ``, and `` tags
- Ready to paste into Flare's Text Editor
## Use Cases
- Import data tables from spreadsheets
- Convert specification sheets to tables
- Migrate tabular data from Excel
- Create tables from calculations or data exports
## Tips
- Format your Excel data before importing
- Use the first row as column headers
- Remove any unnecessary formatting in Excel first
- After pasting, you can apply Flare table styles as needed
---
## Calendar Reminders
Create calendar reminders for topics to help you track review dates, update schedules, and content maintenance tasks.
## Add Google Calendar Reminder
Create a reminder in Google Calendar:
1. Open the topic you want to set a reminder for.
2. Click **Add Google Calendar Reminder** in the To Do & Reminders group.
3. Your browser opens to Google Calendar.
4. A new event is pre-populated with:
- The topic title as the event name
- The topic path in the description
- A default date/time (which you can change)
5. Adjust the reminder details as needed.
6. Click Save in Google Calendar.
## Add Outlook Reminder
Create a reminder in Microsoft Outlook:
1. Open the topic you want to set a reminder for.
2. Click **Add Outlook Reminder** in the To Do & Reminders group.
3. Outlook opens with a new appointment.
4. The appointment is pre-populated with:
- The topic title as the subject
- The topic path in the notes
5. Set your desired reminder date and time.
6. Click Save in Outlook.
## Use Cases
- Schedule content reviews
- Track update cycles for dated content
- Set reminders for seasonal content updates
- Manage SME review schedules
- Track regulatory update requirements
## Tips
- Use reminders for topics that need periodic updates
- Set recurring reminders for regularly updated content
- Coordinate with team members by sharing calendar events
- Document review cycles in your style guide
---
## Quick Documents
Quickly generate PDF, Word, or HTML output from the current topic **or snippet** for fast review and sharing, without building entire targets.
## Quick PDF
Create a PDF from the current topic or snippet:
1. Open a topic or snippet in Flare.
2. Click **Quick PDF** in the Review group.
3. The plugin builds a PDF using a target named **KaizenTarget** (or creates one if it doesn't exist).
4. The PDF opens automatically.
**Snippet Support:** When you use Quick PDF with a snippet, the plugin automatically creates a temporary wrapper topic, builds the PDF, then cleans up the temporary file. This allows you to quickly preview how your snippet will appear in PDF output.
## Quick Word
Create a Word document from the current topic or snippet:
1. Open a topic or snippet in Flare.
2. Click **Quick Word** in the Review group.
3. The plugin builds a Word file using a target named **KaizenWordTarget** (or creates one if it doesn't exist).
4. The Word document opens automatically.
**Snippet Support:** When you use Quick Word with a snippet, the plugin automatically creates a temporary wrapper topic, builds the Word document, then cleans up the temporary file. This allows you to quickly preview how your snippet will appear in Word output.
## Quick HTML
Create a clean XHTML file from the current topic or snippet:
1. Open a topic or snippet in Flare.
2. Click **Quick HTML** in the Review group.
3. The plugin generates a clean XHTML file using a custom target.
4. The HTML file opens in your default browser.
**Snippet Support:** When you use Quick HTML with a snippet, the plugin automatically creates a temporary wrapper topic, builds the HTML file, then cleans up the temporary file. This allows you to quickly preview how your snippet will appear in HTML output.
## Required Setup
The plugin uses special target files for quick builds:
- **KaizenTarget** for PDF output
- **KaizenWordTarget** for Word output
- Custom target for HTML output
If these don't exist, the plugin will create them automatically.
## Use Cases
- Quick review copies for SMEs
- Fast PDF previews without full builds
- Share individual topics or snippets via email
- Review formatting and layout quickly
- Generate samples for stakeholder approval
- Preview snippet rendering in PDF, Word, or HTML format
## Tips
- Much faster than building entire targets
- Useful during iterative writing and review
- Great for spot-checking formatting
- Ideal for single-topic deliverables
- Works with both topics and snippets - snippets are automatically wrapped in a temporary topic for generation
---
## Plugin Settings
Customize the Kaizen Plugin interface by controlling which tabs, groups, and buttons are visible in the Flare ribbon.
## To access settings
1. Click **Settings** in the Help group on any Kaizen Plugin tab.
2. The Plugin Settings window opens.
## Customization Options
### Tab Visibility
Control which plugin tabs appear in the Flare ribbon:
- **Kaizen Plugin** - Main tab with file tools, topic splitter, TOC tools, and information architecture features
- **Cleanup** - Tag replacement, validation, and styling tools
- **Import** - Data import and content conversion tools
- **Productivity** - To-do notes, reminders, and quick document generation
- **Kanban** - In-project Kanban board and topic packaging
### Group Visibility
Within each tab, control which groups are visible:
**Kaizen Plugin Tab:**
- File
- Topic Splitter
- TOC Tools
- Information Architecture
- Backup
- Markdown Plugin
**Cleanup Tab:**
- Styling
- Tracked changes
- Tag Replacer
- Project Analysis
- Image Tools
**Import Tab:**
- Micro Content
- Markdown
- Glossary
- Topic Creator
- Excel to Table
**Productivity Tab:**
- To Do & Reminders
- Review
**Kanban Tab:**
- Kanban
### Button Visibility
Hide individual buttons within groups to further customize your interface.
## Use Cases
- Simplify the interface for specific team roles
- Hide features you don't use
- Create focused workflows for different tasks
- Reduce visual clutter
- Customize for training purposes
## Notes
- **PROMOTIONS** and **Help** groups are always visible (non-removable)
- Settings are saved per user
- Changes take effect immediately
- Settings persist across Flare sessions
## Tips
- Start with all features visible, then hide what you don't need
- Different team members can have different configurations
- Revisit settings as your workflow evolves
- Document your team's standard configuration
---
## Snippet Usage Report
The **Snippet Usage Report** feature analyzes all snippets in your project and shows exactly how many times each snippet is used. This powerful tool helps you identify unused snippets for cleanup and understand snippet dependencies across your project.
## How to Use
1. Open your Flare project
2. Go to the **Productivity** tab in the ribbon
3. Click the **Snippet Usage Report** button
4. Wait for the analysis to complete (a progress dialog shows real-time status)
5. Review the results in the sortable grid
## Features
- **Fast Performance** - Optimized algorithm reads each file only once, making it up to 500x faster than traditional approaches on large projects
- **Progress Dialog** - Shows real-time progress with the current file being scanned and the ability to cancel at any time
- **Sortable Columns** - Click column headers to sort by snippet name, usage count, or files
- **Usage Count** - See exactly how many times each snippet is used
- **File List** - View which files use each snippet (shows first 3, with "..." if more)
- **Quick Navigation** - Double-click any row to open the file(s) where the snippet is used
## Understanding the Results
The report displays three main columns:
- **Snippet Name** - The filename of the snippet (e.g., "ProductName.flsnp")
- **Usage Count** - Number of files where this snippet appears
- **Used In Files** - List of files where the snippet is used
## Double-Click Behavior
When you double-click a row, the plugin intelligently handles different scenarios:
- **Usage Count = 0** - Opens the snippet file itself
- **Usage Count = 1** - Opens the single file where it's used
- **Usage Count > 1** - Prompts you with a dialog:
- Click **Yes** to open all files where the snippet is used
- Click **No** to open only the first file
- Click **Cancel** to do nothing
When opening multiple files, the plugin shows a success/failure count if any files couldn't be opened.
## Common Use Cases
### Find Unused Snippets
1. Run the report
2. Click the **Usage Count** column header to sort
3. Snippets with count = 0 are unused and can potentially be deleted
### Find Rarely Used Snippets
1. Run the report
2. Sort by **Usage Count**
3. Review snippets with count = 1 or 2 to see if they should be expanded or removed
### Update Multi-Use Snippets
1. Find a snippet with high usage count
2. Double-click to open all files where it's used
3. Review and update the snippet knowing exactly where it appears
## Performance
The report is optimized for speed:
- **Small projects** (10-50 snippets, 100 files) - Completes in seconds
- **Medium projects** (100-200 snippets, 500 files) - Completes in 10-20 seconds
- **Large projects** (500+ snippets, 1000+ files) - Completes in 30-60 seconds
The algorithm reads each file only once and searches for all snippets simultaneously, making it dramatically faster than older approaches that would read files repeatedly.
## Tips
- Run the report periodically to maintain project hygiene
- Use the **Refresh** button to update results after making changes
- Consider archiving unused snippets before deleting them
- Check snippet dependencies before major refactoring
- Sort by usage count to prioritize cleanup efforts
---
## Import Micro Content from Excel
Create Flare micro content files (.flmco) from Excel spreadsheets, making it easier to manage FAQ-style content, chatbot responses, and knowledge base articles.
## To import micro content
1. Prepare an Excel file with two columns:
- **Column A**: Micro content phrase (the question or search term)
- **Column B**: Micro content response (the answer or content)
2. Include a header row in your Excel file.
3. Click **Import Micro Content from Excel** in the Micro Content group on the Import tab.
4. Select your Excel file.
5. Choose where to save the .flmco file.
6. Click OK.
7. The micro content file is created and opens in Flare.
## Excel Format Example
| Phrase | Response |
|--------|----------|
| How do I reset my password? | To reset your password, click the "Forgot Password" link on the login page. |
| What are your business hours? | We're open Monday-Friday, 9 AM to 5 PM EST. |
| How do I contact support? | Email support@example.com or call 1-800-555-0100. |
## Tips
- Use clear, natural language for phrases (how users will search)
- Keep responses concise but complete
- Include common question variations as separate entries
- Test your micro content in Flare's built-in preview
- Update your Excel file and re-import when content changes
## Use Cases
- Create FAQ systems
- Build chatbot knowledge bases
- Import help desk articles
- Convert existing Q&A documents
- Maintain micro content in Excel for easier editing
## Benefits
- Edit content in familiar Excel environment
- Collaborate with SMEs who prefer spreadsheets
- Version control your source Excel files
- Bulk edit and manage micro content efficiently
- Quick updates and re-imports
---
## Advanced Tag Replacer (REGEX)
The **Advanced Tag Replacer** provides powerful search and replace functionality for tags, attributes, and content using free text or REGEX patterns across your entire Flare project.
## To use the Advanced Tag Replacer
1. Click **Advanced Tag Replacer** from the **Cleanup** tab.
2. Enter your search text in the **Search for** field:
- Use free text for simple searches
- Use REGEX patterns for advanced matching
3. Click **Search tags** to find all matching tags in your project.
4. Review the list of tags that will be affected.
5. Select the action you want to perform:
- **Replace** - Replace with a different tag
- **Unbind** - Remove the tag but keep its content
- **Delete** - Remove the tag and all its content
- **Wrap** - Wrap the tag in another tag
6. Enter or select the replacement tag (if applicable).
7. Click **Execute** to apply changes.
## Using REGEX Patterns
REGEX (Regular Expressions) allows you to match complex patterns:
### Common REGEX Examples
- `` - Match all paragraph classes starting with "Note"
- `` - Match spans with any color styling
- `` - Match divs with IDs starting with "temp"
### REGEX Tips
- Use `.*` to match any characters
- Use `^` to match the start of a string
- Use `$` to match the end of a string
- Use `[0-9]` to match any digit
- Test your REGEX patterns before executing
## Actions Explained
### Replace
Replaces the matched tag with a different tag while preserving content and compatible attributes.
**Example**: Replace `` with ``
### Unbind
Removes the tag wrapper but keeps all content inside.
**Example**: `text` becomes `text`
### Delete
Removes both the tag and all its content.
**Warning**: This permanently deletes content. Use carefully!
### Wrap
Wraps the matched tag in another tag.
**Example**: Wrap `` in ``
## Safety Features
- **Preview**: See what will be affected before executing
- **Undo**: Reverse changes immediately after execution
- **Backup**: Create a backup before major replacements
## Use Cases
- Clean up legacy HTML from imports
- Standardize inconsistent tagging
- Remove temporary markup classes
- Batch update styling approaches
- Fix bulk tagging issues
## Tips
- Always back up your project before major replacements
- Test on a small subset first when using REGEX
- Use the preview to verify matches before executing
- Keep the undo option available until you verify results
- Document your REGEX patterns for future use
---
## Excel to Auto Suggestions
## Overview
The **Excel to Auto Suggestions** feature allows you to quickly create a Flare Auto Suggestions file (.fltbx) from an Excel spreadsheet. Auto Suggestions in Flare help speed up content authoring by providing commonly used phrases and sentences that authors can insert with a few keystrokes.
## How to Use
1. Navigate to the **Import** tab in Flare
2. In the **Auto Suggestions** group, click **Excel to Auto Suggestions**
3. Select an Excel file (.xlsx) containing your phrases or sentences
4. Choose where to save the Auto Suggestions file (.fltbx)
5. The file will be created and opened in Flare
## Excel File Format
Your Excel file should contain the phrases or sentences you want to use as auto suggestions:
- **First column**: Contains the text for each auto suggestion
- **All rows are imported**: Including the first row (no header row is required)
- **Empty rows are skipped**: Blank cells in the first column are ignored
### Example Excel Structure
| A |
|---|
| Click **Save** to save your changes. |
| For more information, see the User Guide. |
| Contact support if you need assistance. |
## Output
The feature creates a standard Flare Auto Suggestions file (.fltbx) in TBX-Basic format. This file can be:
- Placed in your project's `Project/Advanced` folder
- Shared across multiple projects
- Edited directly in Flare's Auto Suggestion editor
## Tips
- **Consistent phrasing**: Use auto suggestions for phrases that should be written consistently across your documentation
- **Common sentences**: Include frequently-used sentences like instructions, warnings, or contact information
- **Review before import**: Clean up your Excel file to remove duplicates or unwanted entries before importing
- **Combine with existing**: You can create multiple .fltbx files or add entries to an existing file using Flare's editor
## Use Cases
- **Style guide enforcement**: Import approved phrases and terminology
- **Boilerplate content**: Create auto suggestions for standard instructions or disclaimers
- **Migration**: Convert existing phrase lists from other systems to Flare auto suggestions
- **Team standardization**: Share consistent phrasing across a writing team
## Related Features
- [Import Micro Content from Excel](3%20Import%20micro%20content%20from%20Excel.md)
- [Import and Export Glossary](24%20Import%20and%20Export%20Glossary.md)
- [Create Topics from CSV or Excel](10%20Creating%20topics%20from%20CSV%20or%20Excel%20file.md)
---
## Kanban Board
The **Kanban β‘** tab brings lightweight in-project work management to MadCap Flare. Cards are stored as Markdown files under `.kanban/` in the project root, so the board lives with your content and travels through source control.
Plan the work where the work lives.
## To open the board
1. Open a Flare project.
2. Click the **Kanban β‘** tab on the ribbon.
3. Click **Kanban Board**.
The board opens maximized with columns from `.kanban/config.json` (defaults: *backlog*, *ready*, *developing*, *qa*, *blocked*, *done*).
## Packaging topics for a job
The **Add Topic to Card** button lets you collect the set of topics that need to be modified for a particular job, without ever leaving the topic you're working on.
1. Open a topic (or snippet) in Flare.
2. Click **Kanban β‘ β Add Topic to Card**.
3. In the *Attach current topic* dialog:
- Filter and pick an existing card β click **Attach to selected**, **or**
- Click **New card with this topic** to spin up a fresh card pre-loaded with the topic.
If the Kanban Board is already open, the change appears live; if not, the card file is updated on disk and shows up next time you open the board.
## What a card holds
Each card is a Markdown file (`.kanban/cards/card-XXXX.md`) with YAML front-matter:
- **Title**, **Type**, **Assignee**, **Source** (URL or free text), **Column**
- **Description** (Markdown body, with `- [ ] subtask` lines surfacing as live checkboxes)
- **Attached files** β project-relative paths to the topics/snippets/images/TOCs this card covers
- **Suggested files** β the editor automatically suggests files referenced by your attached topics, so you can attach related content with one click
- **Work log** β append-only timestamped entries
## Board features
- **Columns** β manage your workflow via *Manage Columns* (rename, reorder, add)
- **Types** β define card types with body templates via *Manage Types*
- **Checklists** β predefined checklist snippets you can insert into any card body via *Manage Checklists*
- **Search** β filter cards by title, body, assignee, attached file, source, or log entries (press `/` to focus)
- **Drag & drop** β drag cards between columns
- **Annotation board** β a second tab surfaces `madcap:annotation` notes from your topics, grouped by their UPPERCASE prefix (TODO:, FIXME:, REVIEW:, etc.)
- **Archive** β move *done* cards to `.kanban/archive/` to keep the board tidy
- **Themes** β toggle light / dark mode from the window header
- **Live reload** β the board watches `.kanban/cards/` and refreshes automatically when files change (e.g. when teammates push new cards)
## Keyboard shortcuts
- `/` β focus the search box
- `N` β quick-add a card to the first column
- `Enter` β open the selected card
- `Delete` β delete the selected card
- `F5` β reload the board
- `β` `β` `β` `β` β move selection between cards/columns
## Storage layout
```
/
.kanban/
config.json β columns, types, checklists, board settings
cards/
card-0001.md
card-0002.md
...
archive/ β archived (done) cards
```
Everything is plain text, so it commits cleanly to Git/TFS alongside your topics.
## Use cases
- **Migration jobs** β create a card per phase, attach every topic that needs a touch
- **Style sweeps** β package the topics affected by a style change onto one card
- **Review packets** β attach the topics a reviewer needs to read, share the card file
- **Sprint planning** β `backlog` / `ready` / `developing` mirror your engineering board
- **Personal kanban** β quick to-do list with file references that survive across days
## Tips
- Use **Source** to link a card to the GitHub issue, Jira ticket, or doc that triggered the work β the board fetches the page title for you
- Use the *Suggested* panel inside a card to follow snippet/image references and attach related files in one click
- Hide the Kanban tab via **Plugin Settings β Kanban Tab** if you'd rather stay focused
---
## Flare Diagnosis
**Flare Diagnosis** gives you a one-click health check of your entire Flare project. It scans the project on disk, runs 40+ deterministic rules, and turns the results into a plain-language report: what's broken, who it hurts (readers, writers, or the build), and what to do about it.
Everything runs locally and deterministically β no network calls, no data leaves your machine.
## To run a diagnosis
1. Open a Flare project.
2. Go to the **Cleanup β‘** tab.
3. In the *Project Analysis* group, click **Flare Diagnosis**.
A progress dialog shows each scan stage; when it finishes, the report opens in its own window.
## What gets checked
The rules are organized into seven factors:
- **Project Integrity** β filename hazards (zero-width, non-printable, or Windows-illegal characters), paths over 240 characters, case-sensitivity collisions, circular snippet references, empty topics
- **Links & References** β broken xrefs, broken TOC entries, broken image and snippet references, absolute paths, orphan topics, generic link text ("click here"), link casing that works on Windows but 404s on case-sensitive servers
- **Reuse Hygiene** β undefined or unused variables and conditions, unused snippets, duplicate and near-duplicate snippets, low snippet reuse, condition density, deep snippet nesting
- **Style & Markup** β undefined CSS classes used in topics, unused CSS classes, inline `style=` attributes, heading-hierarchy problems, images missing alt text, the same class defined in multiple stylesheets
- **Content Hygiene** β deep TOC nesting, overly flat folder layout, near-duplicate topics
- **Asset Management** β oversized images, unused images, mixed image formats
- **Build Configuration** β near-duplicate targets, target count vs. project size, build complexity, Flare version and output mix
## Reading the report
- **Verdict** β the one-line summary at the top: is the project healthy, does it need work, or can something break your build? It also tells you how many findings are visible to your readers.
- **What this is costing you** β counts of concrete things found in the project (not abstract scores), framed by who pays the price: readers, writers, or builds.
- **Your checklist** β every finding as a prioritized work list, top to bottom. Each row expands to show the affected files, so you can go straight from finding to fix.
## Sharing the report
Click **Save HTML reportβ¦** in the footer to save the full report as a standalone HTML file β handy for sharing with your team, attaching to a ticket, or keeping as a baseline to compare against after a cleanup sweep.
## Tips
- Run a diagnosis **before a migration or big restructure** to find the landmines first.
- Save a report **before and after** a cleanup effort β the delta is your progress report.
- Many findings pair naturally with other Kaizen tools: inline styles β *Remove Local Styling*, unused snippets β *Snippet Usage Report*, missing alt text β *Set ALT Texts*.
---
## Split a topic and create a TOC
Splitting a topic file is a quick and easy way to create a new manual from a single topic file. You can split a topic files by H1-H4.
To split a topic file into separate topic files based on the heading level, and generate a corresponding TOC-file:
1. Open the relevant topic.
2. Click Split by H1 to split by heading level 1, etc.
The topic files and the corresponding TOC are created.
---
## Import a Markdown file to Flare
The plugin only supports the CommonMark specification. For more information, see [CommonMark specification](https://spec.commonmark.org/0.28/).
To import and convert entire folders, or all Markdown files in an open Flare project - you can get the [Markdown Plugin II](../../Markdown%20Plugin%20II/Markdown%20Plugin%20II.md).
To convert a markdown file to a Flare topic:
1. Click **Import Markdown file**.
2. Select the .md file.
3. Save the .html file.
---
## Create a WordCloud from your project, or a folder
To create a Word Cloud from the most used words in your project, or from the topic files in any folder (including sub-folders) - click any of the **WordCloud from...** button.
---
## Farm Glossary Terms from your project
To extract potential glossary candidates from your current project,
1. Click **Farm Glossary Terms**. The Term Farmer window appears.
2. Edit the list of terms, and optionally, add explanations.
3. Click **Create Glossary** to create a new .flglo file and add to your project.
---
## Add a To-Do note to a topic
To add a To-Do note to a topic, insert an annotation with a keyword prefix like:
```
TODO: This is my task.
FIXME: This needs to be corrected.
NOTE: Remember to check this.
REVIEW: Please verify this section.
```
To view all the To-Do Notes in a project, click the **To-Do Notes** button on the Productivity tab.
## Supported Keywords
The To-Do Notes feature recognizes these keywords by default:
- **TODO** - Tasks to be completed
- **FIXME** - Issues that need fixing
- **NOTE** - Important notes or reminders
- **REVIEW** - Items requiring review
- **HACK** - Temporary workarounds
You can add custom keywords using the **+ Add Keyword** button in the To-Do Items window.
## Using the To-Do Items Window
The To-Do Items window shows:
- **Comment** - The annotation text (e.g., "TODO: Fix this")
- **Annotated Text** - The specific text wrapped by the annotation
- **Context** - The surrounding paragraph or element text
- **Topic** - The file containing the annotation
- **Person** - Who created the annotation
- **Keyword** - The keyword type (TODO, FIXME, etc.)
- **Source** - Whether it's from Content or TOC
### Filtering Options
- **Keywords** - Check/uncheck keywords to filter the list
- **Sources** - Include or exclude Content (topics) and TOC entries
- **Search** - Filter by text in any column
### Actions
- **Double-click** a row to open the topic
- **Open Selected** - Open all selected topics
- **Open List As Topic** - Export the list to an HTML file
- **Refresh** - Reload the To-Do items
Settings (selected keywords and TOC preference) are saved automatically.
## How to Insert an Annotation
1. Select some text in your topic
2. Open the **Review** tab in Flare
3. Click **Insert Annotation**
4. In the annotation comment, start with a keyword followed by a colon (e.g., `TODO:`)
---
## Kaizen Plugin
Here's a webinar about the plugin:Β [How to Increase Your Productivity in MadCap Flare with the Kaizen Plugin](https://www.madcapsoftware.com/webinars/how-to-increase-productivity-madcap-flare-kaizen-plugin/).
---
## Release Notes(Kaizen Reviewer)
# 0.0.1 (2022-10-20)
- First alpha release.
---
## Kaizen Reviewer
2022-10-20: TBD.
---
## Release Notes(Mad Quality Plugin II)
| Version | Date | Description |
|---------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1.0.65 | 2026-02-04 | Performance improvements: Violations window now opens instantly even with thousands of violations. Optimized data preparation (runs in background), removed expensive row-by-row processing, and switched to on-demand rendering for tooltips and row styling. |
| 1.0.64 | 2026-02-04 | Added "Copy for LLM" feature: Right-click a violation to copy a formatted prompt for AI assistants like ChatGPT or Claude. Two options available: basic copy and copy with full topic context. The LLM will return the corrected XML element that you can use to fix the issue. |
| 1.0.63 | 2026-01-29 | Fixed duplicate violations bug where the same violation appeared multiple times. Added score explanation tooltip and improved score display. Enhanced XML validation error messages to include line and column numbers. Note: Text highlighting in Flare editor may sometimes only open the file without highlighting due to a known MadCap API limitation. |
| 1.0.62 | 2025-12-12 | Fixed mailto link format for compatibility with New Outlook for Windows. |
| 1.0.61 | 2025-10-22 | Fixed bug in the MadQualityCommander.exe that prevented it from running. |
| 1.0.60 | 2025-09-30 | Fixed .mqignore pattern matching bug where folder paths were incorrectly built. Added missing project boundary check to prevent recursion outside project root. |
| 1.0.59 | 2025-08-13 | CSS selector bug fixes. |
| 1.0.58 | 2025-08-06 | Default Rules no longer automatically appear after deletion & restart. |
| 1.0.57 | 2025-05-20 | Implemented a fix that should resolve the `NullReferenceException` problem. The problem was related to how the application was handling the currently active file, especially when no topic was in focus. |
| 1.0.56 | 2025-05-20 | Bug fix related to the IgnoreContext. |
| 1.0.55 | 2025-05-08 | Bug fix related to XPath attributes. |
| 1.0.54 | 2025-05-07 | Installer updated for Flare 2025. |
| 1.0.53 | 2025-04-18 | Bug fixes|
| 1.0.52 | 2025-04-18 | Bug fixes|
| 1.0.51 | 2025-04-18 | Bug fixes|
| 1.0.50 | 2025-04-18 | Fixed a bug where the trial license would be cut short. |
| 1.0.49 | 2025-01-28 | Bug fix related to scanning TOC files. |
| 1.0.48 | 2024-11-11 | New RegexElementOnly Function. Added a new RegexElementOnly function that enables pattern matching on an element's direct text content while ignoring text in child elements. This helps when you need to validate patterns in parent elements without considering nested content.|
| 1.0.47 | 2024-06-12 | There's now a special rule for checking heading level consistency. Set the context to `check-heading-levels`. |
| 1.0.46 | 2024-05-27 | You can now edit ignored rules in a separate window. |
| 1.0.45 | 2024-04-24 | - Bug fix: There's now a check whether you have a Flare project open before processing. |
| 1.0.44 |2024-03-27 | You can now ignore specific rule violations by right-clicking a violation in the Violations window. |
| 1.0.43 | 2024-03-07 | FIXED: There was a problem related to the caching functionality, where in some cases, the cached response would be triggered even if the rule has changed. |
| 1.0.42 | 2024-03-06 | Performance related bug fixes. |
| 1.0.41 | 2024-02-22 | There's now a button to clear the cache, and the cachefolder moved. |
| 1.0.40 | 2024-02-21 | - The "Anytext" context now covers any element with a text node as a direct child.- Rule violations are now cached for 30 days. |
| 1.0.39 | | - Corrected a problem in the Regex function, where inline elements were not always unbound. |
| 1.0.38 | | - Resolved an issue pertaining to CSS/XPATH conversion.- Addressed a defect causing duplicate entries in the violations list. |
| 1.0.37 | | - Bug fix related to using XPATH instead of CSS in the context. |
| 1.0.36 | | - License agreement update. |
| 1.0.35 | | - License validation bug fix. |
| 1.0.34 | | - Fixed a bug in the license validation code. |
| 1.0.33 | | - Line breaks in CSV file are replaced with a space.- Validate all open files.- Maintain rule files in CSV format. |
| 1.0.32 | 2022-12-14 | - /Project/Users folder exclusion in CSS query scans.- `:emptybreaking` pseudo selector to target empty elements.- Bug fix in licensing functionality.- Changed timeout limit for rules from 15 to 20 seconds. |
| 1.0.31 | 2022-11-25 | - Bug fix: Error message when right-clicking a cell in the Violations window. |
| 1.0.30 | 2022-08-01 | - Bug fixes: - `p[MadCap:conditions='']` context conversion to XPath. - .mqignore function issue for snippets linked from a topic. - FileNameRegex function for all Flare files. |
| 1.0.29 | 2022-05-09 | - New FEATURES: - Run ad-hoc CSS searches. - Validate XHTML of all topics.- BUG fixes: - Cosmetic issue in the preview window. - Bug in the RawRegex function. |
| 1.0.28 | 2022-03-17 | - Removed Google prettyprint dependency.- Non-breaking spaces in HTML preview.- CSV file shows actual word from rule.- MS-20210413120632 rule update.- Bug fix: TOC entry link to bookmark scan issue.**NOTE:** Changes to rules only apply to newly created rule sets. |
| 1.0.27 | 2022-03-08 | - Bug fix to the filter functionality. |
| 1.0.26 | 2022-03-01 | - Extended bug reporting via email.- Bug fix in .ignore-functionality.- Support for non-XElement XNode in xpath statements.- Rule for finding images without ALT texts. |
| 1.0.25 | 2021-12-06 | - Fixed problem with files in /Project/Users/.../Backups in scan.- Changed timeout limit for rules.- REGEX matching with attributes.- New dialog for no broken rules.- XML log mode.- Folders in the rule violation window.- Performance improvements.- Filtering of broken rules.- .mqignore file for ignoring files.- Fixed license validator issue. |
| 1.0.24 | 2021-11-10 | - Fixed License key problem. |
| 1.0.23 | 2021-11-03 | - Correction to REGEX of MS-20210413120609 rule.- Bug fix: `MadCap:concept` conversion.- Updated license terms. |
| 1.0.22 | 2021-10-30 | - Fixed REGEX expressions registration bug.- Changed REGEX of MS-20210413120633.- Fixed `MadCap:concept` conversion to XPath.- Bug fix in REGEX for space at start of element.- Performance improvements.- Change in MS-20210413120548 rule.- Fixed RawRegex function.- ":empty" selector includes non-breaking spaces.- RegexInline function. |
| 1.0.21 | 2021-07-23 | - Use XPath statements for context.- Topics no longer time out at 90 seconds.- Various bug fixes. |
| 1.0.20 | 2021-05-26 | - Corrected spelling errors.- Fixed licensing issue. |
| 1.0.19 | 2021-05-22 | - Enabled silent mode on installer.- Option to link to rule file in remote location.- Added Google Developer Style Guide rules.- Corrections to template rule set.- Results window closes automatically.- Process any Flare XML file. |
| 1.0.18 | | - Bug fix: Plugin crash when a topic contains an image linked to the web. |
| 1.0.17 | | - Fixed a bug in the RawRegex function. |
| 1.0.16 | | - Removed "annotate element" function.- Added timeout for rules and files. |
| 1.0.15 | | - Bug fixes in default rules.- Validation of all default rules.- Added "RawRegex" function.- Corrected bug for Assert type rules. |
| 1.0.14 | | - Disabled write good rules by default.- Corrected bugs in "Word" & "ListOfWord" functions.- Corrected "index is out of bounds" bug.- Changed MS-20210413120543 rule. |
| 1.0.13 | | - Rule template added as default rule set.- FileNameRegex now works with Assert type rules, context, and regex pattern. |
| 1.0.12 | | - Updated GUI texts.- Fallback validation.- Fixed bug in rules spreadsheet conversion. |
| 1.0.11 | | - Performance improvements. |
| 1.0.10 | | - Added "Text" context.- Removed GUI support for adding rules from http-location.- Added "scan a random topic".- Updated internal CSS to XPath engine. |
| 1.0.9 | | - Performance enhancements. |
| 1.0.8 | | - REGEX based rule timeout handling.- Automatic 14 day free trial. |
| 1.0.7 | | - Corrected "FileNameRegex" function bug.- Added more default rules.- Activated all rules.- Added tabs for rule categories.- Extended trial.- Various rule changes. |
| 1.0.6 | | - Corrected en/em-dash rule.- Added message box in results window.- Parallel file processing.- Added progress bar.- Disabled intensive rules in default template. |
| 1.0.5 | | - Fixed "IgnoreCase" setting issue.- Feature to use rules at other locations.- Button to open folders with rules.- Corrected bugs in rule sets.- Corrected resize bug in results window. |
| 1.0.4 | | - Results window no longer stays on top.- Processing modal window behavior. |
| 1.0.3 | | - Regular expressions operate on strings without inline tags.- Added Microsoft Manual of Style rules.- Added progress bar and cancel button. |
| 1.0.2 | | - Regular expressions operate on element string value with tags replaced. |
| 1.0.1 | | - Bug fixes. |
---
## Ignoring Files
To exclude specific files or patterns from being processed by the MadQualityPluginII, you can utilize the `.mqignore` file. This file functions similarly to a `.gitignore` file, allowing you to specify which files the plugin should ignore during its operations.
## Creating and Configuring the `.mqignore` File
1. **Create the `.mqignore` File**:
- You can place a `.mqignore` file in the root directory of your project (where the `.flprj` file is located) or in any subdirectory where you want specific ignore rules to apply.
- The plugin checks `.mqignore` files hierarchically, starting from the file's directory and walking up to the project root.
2. **Edit the `.mqignore` File**:
- Open the `.mqignore` file in a text editor like Notepad.
- Add the filenames or patterns of the files you wish to exclude from processing. Each pattern or filename should be on a new line.
### Examples of `.mqignore` Entries
- **Ignore a Specific File**:
To ignore a specific file, simply add its name to the `.mqignore` file. For example, to ignore `MySnippet.flsnp`, add the following line:
```
MySnippet.flsnp
```
- **Ignore All Files of a Specific Type**:
To ignore all files of a particular type, use a wildcard `*`. For example, to ignore all `.flsnp` files, add this line:
```
*.flsnp
```
- **Ignore Files in a Specific Subdirectory**:
To ignore all files within a specific subdirectory, include the directory name followed by a separator and a wildcard. For example, to ignore all files in the `JAN` subdirectory any of these lines work:
```
\JAN\*
/JAN/*
JAN/*
JAN\*
```
Note: You can use either forward slashes (`/`) or backslashes (`\`) - the plugin handles both, and the leading separator is optional. Mixed separators on the same line (for example `JAN/sub\*`) also work.
- **Ignore Files Based on Complex Patterns**:
You can use standard glob patterns to match multiple files. For example, to ignore all XML files that start with `temp_`:
```
temp_*.xml
```
### Practical Example
Consider this project structure:
```
MyProject\
MyProject.flprj
.mqignore (contains: \Temp\*)
Content\
.mqignore (contains: \JAN\*)
Topics\
MyTopic.htm (processed)
JAN\
Read_the_manual.htm (ignored by Content\.mqignore)
Temp\
Draft.htm (ignored by root .mqignore)
```
When processing `Read_the_manual.htm`:
1. Plugin checks `Content\JAN\` - no `.mqignore` found
2. Plugin checks `Content\` - finds `.mqignore` with `\JAN\*` pattern
3. File matches pattern `Content\JAN\*` β **File is ignored**
## How It Works
- When the Mad Quality Plugin processes a file, it searches for `.mqignore` files starting from the file's directory and walking up the directory tree.
- The search continues until it either:
- Finds a matching ignore pattern in any `.mqignore` file (the file is then ignored), or
- Reaches the project root directory (where the `.flprj` file is located) without finding a match (the file is processed)
- If a file matches any pattern in any `.mqignore` file along the path, it is excluded from all plugin processing activities.
- This hierarchical approach allows you to have different ignore rules at different levels of your project:
- Place a `.mqignore` in your project root for project-wide ignore patterns
- Place additional `.mqignore` files in subdirectories for folder-specific ignore patterns
- The plugin will never search outside your project root (beyond the `.flprj` file location)
- This setup helps in focusing the quality checks on relevant files and can improve processing times by skipping unnecessary files.
## Best Practices
- **Regular Updates**: Keep the `.mqignore` file updated as new files or directories are added to your project that you wish to ignore.
- **Use Comments**: You can add comments in your `.mqignore` file by starting the line with a `#`. This is useful for documenting why certain files or patterns are ignored.
```
# Ignore backup snippets
*.bak
```
By properly configuring the `.mqignore` file, you can efficiently manage which files are processed by the Mad Quality Plugin, ensuring that the plugin's operations are both relevant and optimized for your project's needs.
---
## Install the Mad Quality Plugin II
> If you don't already have a license - you can get one from [https://gum.co/madquality2](https://gum.co/madquality2)
1. Download the latest installer from [https://www.improvementsoft.com/Content/Plugins/plugins-mad-quality-ii.htm](https://www.improvementsoft.com/Content/Plugins/plugins-mad-quality-ii.htm)
2. Close Flare
3. Run the installer
4. Start Flare again
5. Go to **File > Options > Plugins** and click **Enable**. The plugin now appears in the ribbon.
> The plugin does not support the Tool Strip interface
---
## Setting up validation rules
For examples of rules, see [Examples](./5%20Examples.md).
For a list of supported CSS syntax, see [CSS Syntax](4%20CSS%20Syntax.md).
For instructions on how to install the plugin, see [Install the Mad Quality Plugin](2%20Install%20the%20Mad%20Quality%20Plugin.md).
> Setting up rules requires Microsoft Excel, or a software that can edit .xlsx files.
A rule consists of these parts:
**Name**
- The name of the rule, for example "MS-20210417104127".This string appears in the report and makes it easier to find the rule in the ruleset.
**Enabled**
- Enables (TRUE) or disables (FALSE) the rule.If you disable a rule, the plugin ignores it in the ruleset (does not run it).
**Description**
- A description of the rule and its source.This string appears in the report.For example "[https://docs.microsoft.com/en-us/style-guide/acronyms](https://docs.microsoft.com/en-us/style-guide/acronyms)".
**Message**
- A detailed message about the violation.This string appears in the report.For example "`Avoid using acronyms in a title or heading.`"
- You can add `%s` and `%t` to your message string to include the Regular Expression matches. For example, for a rule with the `Word` function with the parameter `checkbox:check box`, the message could be `Do not write: '%s'. Write: '%t'.`. The report would show this to the writer: `Do not write: 'checkbox'. Write: 'check box'`.
**Type**
- The type determines whether to **assert** or **report** the presence of a pattern.
- If you select **Assert**, the report shows a rule violation only if the pattern does **not** appear in your content.For example, to check if H1 appears, enter `h1:nth-of-type(1)` in the **Context** column.This rule would be violated only if a topic / snippet does **not** contain one ``.
- If you select **Report**, the report shows a rule violation only if the pattern **does** appear in your content.For example, to check if H-tags contain a `` tag, enter `:header:has(br)` in the **Context** column.This rule would be violated only if a heading tag **contains** a `` tag.
**Context**
- The CSS-based context to apply the rule in. For example, to apply it to all paragraph `` elements, the context would be `p`.I recommend this reference: [MDN CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) For more information, see [CSS Syntax](4%20CSS%20Syntax.md).
**IgnoreContext**
- The CSS-based context to_not_ apply the rule in.
> It is possible to use XPath in the context and IgnoreContext.Examples:- To match all paragraphs, enter: `xpath:.//p`- To match a topic that has the `xml:lang="VALUE"`, enter: `xpath:.//html[@xml:lang]`
**Function**
- The function of the rule. Each function, except the **None** function takes one or more parameters, configured in the **Parameters** column.
| Function | Description | Clarification / Example |
| ------------- | --------------------------------------------------------------------- | ----------------------------------------------------- |
| **None** | The rule just asserts or reports the presence of the context element. | To find a heading wrapped in a paragraph tag, you can configure this Context:`p > h1` |
| **Regex** | The rule uses the RegEx syntax from the **Parameters** column to check for the pattern match only in the inner text value of an element from the **Context** column.All inline elements are unbound.| The rule analyzes the string`Lorem ipsum dolor`as`Lorem ipsum dolor`. |
| **RawRegex** | The rule uses the RegEx syntax from the **Parameters** column to check for the pattern match in the entire element from the **Context** column.All inline elements are kept. | The rule analyzes the string`Lorem ipsum dolor`literally as`Lorem ipsum dolor`.For example, to find two adjacent variables with a missing space between them, you can configure:- Context = `p, li`- Parameters = `<\/MadCap:variable>` tag, you can configure:- Context = `h1, h2, h3, h4, h5, h6, p`- Parameters = `\ To develop and test regular expressions, I recommend these web sites: [RegEx101](https://regex101.com/), [RegEx Pal](https://www.regexpal.com/).
**IgnoreCase**
- For rules that contain RegEx in the **Parameters** column, this setting determines whether to ignore (TRUE) or not (FALSE) the letter-case of the matching text.
**Parameters**
- The parameters for the different functions.For example, a RegEx syntax.See the **Function** section above.
**Score**
- A penalty score to apply when a rule is broken.Use this to let writers know how serious a broken rule is.You decide on the scale and its meaning.
**FileFilters**
- This is a comma-separated wildcard based text that lets you assign rules to different file types, or files with a specfic prefix.For example `*.htm,*.html,*.flsnp` matches topics and snippets.
---
## CSS Syntax
The following CSS syntax is supported.
> To use XPath syntax, prefix the `context` value with `xpath:`
## Special tags
- `Text` all p, li (without p), and td (without p) elements.
- `TextAndHeaders` also include h1 - h7.
- `AnyText` includes any element with text. For example, a `div` with text, e.g. `text`.
- `:headers` all h1 - h7 elements.
## Tag Selectors
- `*` all elements
- `div` all div tags
- `div,p` all divs and paragraphs
- `div p` paragraphs inside divs
- `div > p` all p tags, one level deep in div
- `div + p` p tags immediately after div
- `div ~ p` p tags preceded by div
- `.classname` all elements with class
- `#idname` element with ID
- `div.classname` divs with certain classname
- `div#idname` div with certain ID
- `#idname *` all elements inside `#idname`
## Attribute Selectors
- `a[target]` a tags with the target attribute.
- `a[target="_blank"]` `a` tags where the `target` attribute equals `_blank`
- `[title~="chair"]` title element containing a word
- `[class^="chair"]` class starts with chair
- `[class|="chair"]` class starts with the chair word
- `[class*="chair"]` class contains chair
- `[class$="chair"]` class ends with chair
- `[class%="\bchair\b"]` class matches the regex `\bchair\b`
## Pseudo Selectors/Functions
- `div:empty` element with no children
- `p:emptybreaking` empty element with only spaces, but not non-breaking spaces.
- `p:first-of-type` first of some type
- `p:last-of-type` last of some type
- `:not(span)` element that's not a span
- `p:first-child` first child of its parent
- `p:last-child` last child of its parent
- `p:nth-child(2)` second child of its parent
- `p:nth-child(3n+1)` nth-child (an + b) formula
- `p:nth-last-child(2)` second child from behind
- `p:nth-of-type(2)` second p of its parent
- `p:nth-last-of-type(2)` ...from behind
- `p:only-of-type` unique of its parent
- `p:only-child` only child of its parent
- `p:has(br)` element that contains another element
- `p:contains(text)` element that contains *text*
- `p:regex('regex')` element that matches the regex (case sensitive) `'regex'`.
- `p:iregex('regex')` element that matches the regex (case insensitive) `'regex'`.
---
## Special Rules
- If you set the **Context** to `check-heading-levels`, the plugin checks if the heading levels are consistent (e.g. flagging occurrences of `h1` followed by `h3`).
---
## Example rules
To see the default rules that the plugin comes with, see this Excel file: [https://github.com/msander1983/MadQualityPluginRelease/raw/main/RuleTemplate.xlsx](https://github.com/msander1983/MadQualityPluginRelease/raw/main/RuleTemplate.xlsx)
For information about setting up rules, see [Setting up validation rules](3%20Setting%20up%20validation%20rules.md).
---
## Command Line Interface
The **Mad Quality Commander** CLI file `MadQualityCommander.exe` lives in the `C:\...\Flare.app` folder.
To validate all topics and snippets in a folder against a set of rules, use this syntax:
`C:\>βC:\....\Flare.app\MadQualityCommander.exeβ βC:\...\my folderβ βC:\...\my rules.xlsxβ βC:\....\myLog.txtβ
`
- To include subdirectories, use the `/i` flag.
- To format the log as XML, use the `/xml` flag.
- To use the average score of the broken rules per file as the exit code, use the `/score` flag.
---
## FAQs
**How do I delete a rule set?**
1. Close Flare
2. Go to `C:\Users\{YOUR USER NAME}\Documents\Mad Quality Plugin II`
3. Delete or move the corresponding .xlsx file from the folder
4. Restart Flare.
**What does the "|" symbol mean in the result window?**
This means "or". (And the symbol is pronounced "pipe".)
**What about snippets in my topics?**
They're fine: The plugin checks all snippets, too. However, it will miss some structural elements. For example, the plugin will flag a missing heading or a missing concept tag if these elements are not in the topic, but in the snippet. You can easily detect these false positives in the result window and ignore them.
**What about conditions in my topic?**
They're fine: When you verify a topic that contains conditions, some results about topic structure can be false positives because the plugin currently doesn't distinguish between different conditions.
**What about Tracked Changes in my topic?**
Proceed with care: Before verifying a topic, ensure your topic does not contain tracked changes. Nothing bad happens, but you will not get meaningful results for the parts in the topic code where tracked changes are present.
**How can I exclude elements based on the applied condition?**
To for example ignore paragraphs with a condition, use this context: ``p:not([condition*='Default.Mobile'])``, where you replace ``Default.Mobile`` with the condition you'd like to exclude.
**How can I use AI to help fix violations?**
Right-click on any violation in the results window and select "Copy for LLM" or "Copy for LLM (with topic context)". This copies a formatted prompt to your clipboard that you can paste into an AI assistant like ChatGPT, Claude, or Copilot. The AI will analyze the issue and return the corrected XML element. The "with topic context" option includes the full topic content for better context.
**Can I exclude a file from processing?**
Yes. You can exclude files from processing using `.mqignore` files. Create a text file named `.mqignore` in your project root or in any subdirectory. Add file patterns you want to ignore, one per line:
```txt
# Ignore specific files
My topic.htm
Draft_*.htm
# Ignore all files in a subdirectory
\Temp\*
# Ignore all files of a type
*.bak
```
The plugin searches for `.mqignore` files hierarchically, starting from the file's directory and walking up to the project root. See "10 Ignoring files.md" for detailed documentation on patterns and how the ignore functionality works.
---
## Sharing rules using OneDrive
To share rules with your team using OneDrive:
1. Add the rule file in the `c:\users\...\Documents\Mad Quality Plugin II` folder to OneDrive.
2. Share the folder with your team members
Each team member then needs to :
1. Install and sign into OneDrive on their computer so that it syncs locally on their computer. This creates the local folder on their machine that they can use as a link.
2. Open the folder on OneDrive in their web browser.
3. Select, βAdd shortcut to OneDriveβ to sync the rules folder to their computer
4. In Flare, open the **Mad Quality Plugin II** tab and then click **Add Rules from a link** and enter the local path to the rule file, for example: `c:\Users\ExampleUser\OneDrive\MadQualityRules\Rules.xlsx`
5. Select OK.
---
## Rule Examples
To match a variable where the following text node doesn't start with a space:
`xpath:.//MadCap:variable[following-sibling::text()[not(starts-with(.,' '))]]`
To match a variable wher the preceding text node doesn't end with a space:
`xpath:.//MadCap:variable[preceding-sibling::text()[not(matches(.,'.*\s+$'))]]`
To match a variable with a missing space at either end:
`xpath:.//MadCap:variable[preceding-sibling::text()[not(matches(.,'.*\s+$'))] or following-sibling::text()[not(starts-with(.,' '))]]`
To find an `` element that's not covered by a condition the contains the text `Online`:
`xpath:.//a[not(ancestor-or-self::*[contains(@MadCap:conditions,"Online")])]`
To find elements where there is one or more digits that are not followed by a unit:
```regex
\d+(#|#\/cmΒ³|#\/h|#\/km|#\/kWh|#\/l|#\/m|#\/mi|#\/min|#\/mmΒ³|#\/mΒ³|#\/s|#\/test|#\/Ws|%|%\/s|%mass|%sβ»ΒΉ|%vol|'|\(rev\/min\)\/\(km\/h\)|1\/\(ft\/min\)|1\/\(km\/h\)|1\/\(m\/s\)|1\/\(mm\/s\)|1\/cmΒ³|1\/K|1\/kmph|1\/kn|1\/m|1\/min|1\/min\/s|1\/mph|1\/mΒ³|1\/s|1\/sΒ²|1\/Β°C|\"|A|Ah|As|at|atm|bar|bar\/s|bar\/Β°|bit|Btu|btu\/lb|Btu\/s|byte|cc|cc\/cycle|cc\/s|cd|cfm|cfs|ch|cm|cm\/s|cmΒ²|cmΒ³|cmΒ³\/min|cmΒ³\/s|cmΒ³\/stroke|Coulomb|Count\/h|Count\/kWh|Count\/min|Count\/s|Count\/test|Count\/Ws|d|dB\(A\)|dm|dmΒ²|dmΒ³|dmΒ³\/s|F|Fraction|FSN|ft|ft*lbf|ft*lbf\/s|ft*pdl|ft\/min|ft\/sΒ²|ftΒ²|ftΒ³|ftΒ³\/min|ftΒ³\/s|g|g\/bhph|g\/cmΒ³|g\/h|g\/inj|g\/kg|g\/km|g\/kWh|g\/l|g\/mi|g\/min|g\/MJ|g\/mol|g\/mΒ³|g\/s|g\/stroke|g\/Ws|gal\(UK\)|gal\(US\)|gal\(US\)\/h|gal\(US\)\/min|Gbit|GHz|Gibit|gon|gph\(US\)|gpm\(US\)|grav|H|h|hp|hPa|hph|Hz|in|in*lbf|in*ozf|in\/s|inH2O|inHg|inΒ²|inΒ³|J|J\/cmΒ³|J\/K|J\/kg|J\/kgK|J\/m|J\/molK|J\/mΒ³|J\/s|JsΒ²|K|kA|kbit|kcal|kcal\/s|kg|kg\/\(msΒ²\)|kg\/cmΒ²|kg\/dmΒ³|kg\/h|kg\/inj|kg\/J|kg\/kg|kg\/kmol|kg\/kWh|kg\/l|kg\/m|kg\/min|kg\/mol|kg\/mΒ³|kg\/s|kg\/stroke|kg\/Ws|kgf|kgf\/cmΒ²|kgfm|kgfmsΒ²|kgm\/sΒ²|kgmΒ²|kgmΒ²\/sΒ³|kHz|Kibit|kJ|kJ\/K|kJ\/kg|kJ\/kgK|kJ\/kmolK|km|km\/h|km\/h\/s|km\/l|km\/m|kmol|kmol\/kg|kmol\/kWh|kmol\/s|kmph|kmΒ²|kmΒ³|kn|kN|kN\/\(m\/s\)|kN\/s|kNm|kNm\/s|kOhm|kp|kp*m\/s|kp\/cmΒ²|kPa|kPa\/s|kpm|krev\/min|kV|kV\/V|kW|kW\/mΒ²|kWh|kWh\/K|kWh\/l|l|l\/100 km|l\/h|l\/min|l\/s|l\/s\/kPa|l\/s\/mmAq|l\/s\/Pa|l\/tonkm|lb|lb-ft|lb-ft\/rpm|lb-ft\/s|lb-ft\/Β°|lb\/h|lb\/min|lbf|lbf\/ftΒ²|lbf\/ftΒ²s|lbf\/ftΒ²ss|lbf\/inΒ²|lbf\/inΒ²\/Β°|lbf\/mph|lbf\/mphΒ²|lbf\/mphΒ³|lbf\/mphβ΄|lbs\/ftΒ³|m|m\/h\/rpm|m\/m|m\/mΒ³|m\/s|m\/s\/rad|m\/sΒ²|mA|MassFract|mbar|Mbit|mF|mg|mg\/inj|mg\/kg|mg\/km|mg\/mi|mg\/mΒ³|mg\/stroke|mH|MHz|mi|mi\/gal UK|mi\/gal US|Mibit|min|miΒ²|miΒ³|MJ\/kg|mkgf|mm|mm\/m|mm\/s|mmH2O|mmHg|mmol|mmol\/s|mmWS|mmΒ²|mmΒ²\/s|mmΒ³|mmΒ³\/p|mmΒ³\/rev|mmΒ³\/stroke|MN|mOhm|mol|mol\/kg|mol\/kmol|mol\/kWh|mol\/mol|mol\/s|mol\/Ws|MolarFraction|MPa|mPa|MPa\/s|mph|mph\/s|ms|mV|mV\/V|MW|mW|mWb|mΒ²|mΒ²\/s|mΒ³|mΒ³\/cycle|mΒ³\/h|mΒ³\/inj|mΒ³\/m|mΒ³\/min|mΒ³\/mkg|mΒ³\/mmH2O|mΒ³\/ms|mΒ³\/rad|mΒ³\/s|mΒ³\/s\/Pa|mΒ³\/stroke|N|N\/\(km\/h\)|N\/\(km\/h\)Β²|N\/\(km\/h\)Β³|N\/\(km\/h\)β΄|N\/\(m\/s\)|N\/\(m\/s\)Β²|N\/\(m\/s\)Β³|N\/\(m\/s\)β΄|N\/\(rad\/s\)Β²|N\/cmΒ²|N\/m|N\/mΒ²|N\/s|nF|Nm|Nm\/\(km\/h\)|Nm\/\(km\/h\)Β²|Nm\/\(km\/h\)Β³|Nm\/\(m\/s\)|Nm\/\(m\/s\)Β²|Nm\/\(m\/s\)Β³|Nm\/\(rad\/s\)|Nm\/\(rad\/s\)Β²|Nm\/rad|Nm\/rpm|Nm\/rpmΒ²|Nm\/s|Nms|Number\/h|Number\/kWh|Number\/min|Number\/s|Number\/Ws|nWb|Ohm|oz|p|Pa|Pa\/rad|Pa\/s|particles|particles\/h|particles\/kWh|particles\/min|particles\/s|particles\/test|particles\/Ws|pF|poncelet|ppm|ppmC|ppmP|PS|PSh|psi\/Β°|rad|rad\/m|rad\/Nm|rad\/s|rad\/sΒ²|ratio|rev\/min|rev\/min\/mph|RoC&|RoC\/|RoC=|rpm|rpm\/s|s|sm|smΒ²|smΒ³|sr|sβ»ΒΉ|t|Tbit|TestPressureUnit|Tibit|ton\(UK\)|ton\(US\)|Torr|V|V\/V|VA|VolFract|VolumeFraction|W|W\/cmΒ²|W\/mΒ²|Wb|Wh|Wh\/km|Ws|Ws\/K|yd|ydΒ²|ydΒ³|Β°|Β°\/Nm|Β°C|Β°F|Β΅A|Β΅F|Β΅g|Β΅H|Β΅m|Β΅m\/m|Β΅mol|Β΅mol\/s|Β΅mΒ²|Β΅mΒ³|Β΅Ohm|Β΅s|Β΅V\/V|Β΅Wb|ΞK|ΞΒ°C|ΞΒ°F)
```
Find non-breaking spaces:
`td:iregex('^\x20+$')`
To check if something is covered by a condition - you can use:
`xpath:.//a[not(ancestor-or-self::*[contains(@MadCap:conditions,"Online")])]`
---
## Mad Quality Plugin II
With the Mad Quality Plugin II you can automatically validate the quality of your topics in Flare.
You can check for both structural problems,
- such as `Lorem ipsum`,
- and for language problems, such as the passive voice in `The plugin is used for checking quality`
The main things you can use it for are:
1. Self-editing - making sure your content is as good as possible before publication, or handing it over to a human editor.
2. Enforcing style guide compliance in a team of writers.
The plugin comes pre-loaded with a set of rules based on the [Microsoft Manual of Style](https://docs.microsoft.com/en-us/style-guide/welcome/), the [Google developer documentation style guide](https://developers.google.com/style), as well as a collection of structural rules, and you can also set up your own rules.
> This project is neither maintained nor endorsed by Microsoft, or Google.
> Setting up rules requires Microsoft Excel, or a software that can edit .xlsx files.
---
## Release Notes(Markdown Plugin II)
See https://github.com/msander1983/MarkdownPluginRelease/releases
---
## Markdown Plugin
The plugin is based on the CommonMark specification. For more information, see the [CommonMark specification](https://spec.commonmark.org/).
You can download the latest installer from [https://github.com/msander1983/MarkdownPluginRelease/releases/latest](https://github.com/msander1983/MarkdownPluginRelease/releases/latest).
To purchase a license, go to [gum.co/markdown2](https://gum.co/markdown2).
## Import to Flare
* Import a folder with Markdown files to Flare topics.
* Import a folder with Markdown files to Flare snippets.
## Export to Markdown
* Export a Flare topic or snippet to a Markdown file.
* Export a folder of topics and snippets to Markdown files.
## Convert to Markdown
* Convert the current topic to Markdown.
* Convert a folder of topics and snippets to Markdown.
* Convert all topics and snippets in your Flare project to Markdown.
## Refresh from Markdown
* Overwrite the content of the current topic with the converted content from its corresponding Markdown file.
* Refresh all topics and snippets in a folder from the corresponding Markdown files.
* Refresh all topics and snippets in your Flare project from Markdown.
> If a topic is called `Topic.htm`, the corresponding Markdown file would be `Topic.md`, and for a snippet called `Snippet.flsnp`, the corresponding Markdown files is `Snippet.flsnp.md`.
## Misc
* Convert a Flare topics to a Flare TOC file
## Markdown Editor
Use the built-in Markdown editor to see what your Markdown is converted to with the plugin.
### Settings
The settings for converting Markdown to Flare topics are set in a file called `MarkdownSettings.xml`, which is placed either in your Flare project, or in your application data folder in Windows. If a Flare project has a settings file - that file takes precedence over the settings file in the application data folder.
```xml
truefalsefalsefalsefalsefalsefalsefalsefalsefalsetrue
```
#### Import settings
- Convert to MadCap Code Snippet
- Convert local links (and #-links) to cross-references
- Convert commented out html tags (``) to HTML
- Convert //comments to MadCap:annotations
- Copy images upon import
- Import tables without adding headers to tables that don't have them.
- Export YAML meta data.
- Convert `[[Wiki links]] `to xrefs (only relevant for folder import).
- Add GitHub repo URL meta data to imported files. /blob/main/ only
- Convert `[block:image]` and `[block:code]` elements to `` and ` `respectively.
- Convert #keyword to ``
- Merge adjacent empty table cells in a row.
- Import tables with `` and ``
- Convert #-links to lower case
#### Export settings
- Export HTML elements without attributes to keep the Markdown clean.
- Convert MadCap:xref to regular links on export.
- Export unsupported tags as `` comments.
### YAML meta data
If a Markdown file contains YAML dat, the YAML tags are converted to meta-tags in Flare.
* There are a few special cases that are processed differently:
* **conditions** are converted to the conditions of the topic or snippet.
* **conditionTagExpression** are converted to the snippet conditions of the topic or snippet.
* **fileTags** are converted to file tags for the topic or snippet.
For example,
```yaml
description: Lorem ipsum dolor
keywords: lorem, ipsum, dolor
category: lorem
```
is imported into Flare as
```html
```
and this YAML code
```yaml
---
conditions: Default.Mobile,Default.Tablet
conditionTagExpression: include[Default.Mobile], exclude[Default.Tablet]
fileTags: Author.Author1,Author.Author2
---
```
is imported as
```html
```
## MarkdownCommander.exe CLI
With the MarkdownCommander CLI you can import and export files using the command line.
> The **MarkdownCommander.exe** file is located in your `C:\...\Flare.app` folder.
To import Markdown files to topics:
```
C:\...\Flare.app\>MarkdownCommander -import "C:\...\from-folder"" ""C:\...\to-folder"
C:\...\Flare.app\>MarkdownCommander -import "C:\...\from-folder\myfile.md" "C:\...\to-folder"
C:\...\Flare.app\>MarkdownCommander -import "C:\...\from-folder\myfile.md" "C:\...\to-folder\myfile.htm"
```
To export topics to Markdown files:
```
C:\...\Flare.app\>MarkdownCommander -export "C:\...\from-folder"" ""C:\...\to-folder"
C:\...\Flare.app\>MarkdownCommander -export "C:\...\from-folder\mytopic.htm" "C:\...\to-folder"
C:\...\Flare.app\>MarkdownCommander -export "C:\...\from-folder\mytopic.htm" "C:\...\to-folder\mytopic.md"
```
| Flag | Comment |
| --- | ---|
| /f | Force overwrite |
| /i | Include sub-folders |
| /t | Generate output to console (single file only) |
| /s | Suppress dialogs. |
| `/settings:[file]` | Uses a specific settings file for the Markdown import, e.g. `/settings:"C:\users\mattias\my files\mySettings.xml"` |
To generate a TOC from a folder structure:
```
C:\>MarkdownCommander -toc "C:\my folder" "C:\...\myToc.fltoc"
```
> **NOTE:** If a folder is called "/My Folder/" and has a corresponding HTM file called "My Folder.htm" - that file is used is the parent topic for the node of that folder. Otherwise the folder node will be empty.
## Ignoring files
* To keep files from being imported, you can set up a `.markdownimportignore` file in the source folder.
* To keep files from being exported, you can set up a `.markdownexportignore` file in the source folder.
The syntax is based on wildcards, where
* `*` represents a range of wildcard characters, and
* `?` represents a single wildcard character
To ensure that the .ignore rules are processed relative to the folder of the .ignore file the line in the ignore file must contain `\`.
### Examples
| Rule | Comment |
| --- | ---- |
| `*\Lorem.md` | Excludes the files called `Lorem.md` in any subfolder to the folder with the rule file |
| `\Lorem.md` | Excludes the `Lorem.md` file from the folder with the rule file |
| `*Lorem*` | Excludes any file with `Lorem` in its full path. |
---
## Supported table formats
For tables with headings - use this syntax:
```md
| Heading | Heading |
| ------- | ------- |
| Data | Data |
| Data | Data |
```
For tables without headings - use this syntax:
```md
| Data | Data |
| Data | Data |
| Data | Data |
```
---
## Installation and Setup
## System Requirements
- MadCap Flare 2021 r3 or later
- Windows 10 or later
## Installation Steps
1. Download the Style Stack Plugin installer from your Improvementsoft account
2. Close all instances of MadCap Flare
3. Run the installer and follow the setup wizard
4. Start MadCap Flare
5. The Style Stack interface will automatically appear in your Flare ribbon
## Activation
1. Click the Style Stack tab in the Flare ribbon
2. Click "Activate License"
3. Enter your license key
4. Click "Activate"
Your Style Stack Plugin is now ready to use!
---
## Using Style Stack
## The Style Stack Interface
Style Stack adds a new panel to your Flare interface where you can select multiple classes for any element. The panel shows all available classes from your stylesheets, organized by category.
## Applying Multiple Classes
1. Select any element in your topic
2. Open the Style Stack panel
3. Check the boxes next to the classes you want to apply
4. The classes are instantly applied to your element
## Auto-Complete Support
As you type in the search box, Style Stack suggests matching classes from your stylesheets. This makes it easy to find the exact classes you need, even in large stylesheets.
## Managing Applied Classes
- View all currently applied classes in the "Applied Classes" section
- Uncheck a class to remove it
- Reorder classes by dragging them up or down in the list
- Clear all applied classes with one click
## Class Compatibility
Style Stack automatically handles class specificity and inheritance according to standard CSS rules. If classes have conflicting properties, the last class in the list takes precedence.
---
## Best Practices
## Organizing Your Classes
- Create single-purpose classes that do one thing well
- Use clear, descriptive names for your classes
- Group related classes into logical categories in your stylesheet
- Document the purpose of each class in your stylesheet
## Effective Class Combinations
- Start with the base class that defines the main purpose of the element
- Add modifier classes to adjust appearance or behavior
- Keep combinations simple and meaningful
- Test combinations to ensure they work as expected
## Performance Tips
- Limit the number of classes per element to maintain clarity
- Use class combinations that make semantic sense
- Create class presets for commonly used combinations
- Regular cleanup of unused class combinations
## Common Patterns
### Content Types
```css
.note { /* Base styling for notes */ }
.warning { /* Warning-specific styling */ }
.tip { /* Tip-specific styling */ }
```
### Visual Styles
```css
.highlighted { /* Highlight background */ }
.bordered { /* Add borders */ }
.rounded { /* Round corners */ }
```
### Layout
```css
.centered { /* Center content */ }
.full-width { /* Full width container */ }
.condensed { /* Reduced spacing */ }
```
## Example Combinations
- `note warning` - Creates a warning note
- `panel highlighted rounded` - A highlighted panel with rounded corners
- `table condensed bordered` - A compact table with borders
---
## Style Stack Plugin
Finally, you can apply multiple style classes to any element in MadCap Flare! Style Stack brings the flexibility of modern web development to your documentation, letting you combine classes just like you would in HTML/CSS.
Stop creating endless combinations of single-purpose classes. With Style Stack, you can layer existing classes to achieve exactly the look you want. Need a paragraph that's both a note and a warning? Or a div that's a panel, highlighted, and condensed? Just check the classes you want to apply - it's that simple.
## Key Features
- Apply multiple classes to any element in Flare
- Intuitive auto-complete interface that integrates seamlessly with Flare
- Works with all your existing stylesheets
Transform how you style your documentation. Get Style Stack today and join technical writers who've discovered the power of multiple class selection in Flare.
---
## Word Import Plugin
The Word import plugin is a no-frills importer for Flare. It imports only the basic styles of the Word document, and automatically imports images.
---
## Enhance Responsiveness with the Element
When working with MadCap Flare, generating responsive HTML output is key for accessibility across various devices. The HTML `` element is an essential tool for this purpose, ensuring images in your documentation adapt seamlessly to different screen sizes and resolutions.
## Simplified Approach
The `` element allows you to define multiple image sources for different viewing conditions. This flexibility is vital for technical documentation, where clarity and readability are paramount.
## Usage in Flare
In your Flare project:
```html
```
This code serves `large-image.jpg` for screens wider than 800px, with `default-image.jpg` as a fallback for smaller screens or unsupported browsers.
## Benefits
1. **Responsive Design**: Tailor images to fit various devices, enhancing user engagement.
2. **Efficiency**: Reduce the need for multiple image versions in your Flare project.
3. **Clarity**: Ensure images are crisp and clear, regardless of device or screen size.
Incorporating the `` element into your MadCap Flare HTML output is a straightforward yet impactful way to elevate your technical documentation. It's an easy step towards creating more responsive, device-friendly content.
---
## Implementing CSS Clamp in MadCap Flare
## What is CSS `clamp()`?
CSS `clamp()` is a function for responsive font sizing in web design, adjusting font size within specified minimum, preferred, and maximum sizes based on viewport size.
## Using `clamp()` in MadCap Flare
To use `clamp()` in MadCap Flare for web outputs, update your CSS with a rule like `.dynamic-font { font-size: clamp(1rem, 2vw, 3rem); }` and apply this class to elements in Flare.
:::note
`clamp()` is not applicable to PDFs generated in Flare; adjust font settings for PDFs separately.
:::
## Additional Resources
- [CSS `clamp()` documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp)
- [Browser support for `clamp()`](https://caniuse.com/?search=clamp())
---
## Supercharge Tables in Flare
Supercharge your tables in MadCap Flare using the DataTables JavaScript plug-in. As a bonus it makes your tables mobile friendly automatically.
Just add these tags to your template page `` element:
```html
```
For more information, see https://datatables.net/.
---
## Using Post Build Events in Flare for CSS Customization
Post build events in MadCap Flare can append styles to the skin-specific CSS, enabling customization of elements not available in the Flare skin editor. This is particularly useful for Tripane skin where some elements, like the search bar proxy, lack direct support for modifications.
1. **Create Custom CSS and JavaScript**: Prepare your additional CSS and JavaScript files with the desired styles and functionalities.
2. **Configure Post Build Events**: In your Flare project, open your target, and looks under the 'Build Events' tab, add the following batch commands as post build events:
```batch
type "$(ProjectDirectory)Content\Skin_CSS_additions.css" >> "$(OutputDirectory)\Skins\Default\Stylesheets\Styles.css"
type "$(ProjectDirectory)Content\Skin_Javascript_additions.js" >> "$(OutputDirectory)\Resources\Scripts\MadCapAll.js"
```
These commands append your custom CSS and JavaScript to `Styles.css` and `MadCapAll.js` in the output directory.
3. **Build the Project**: Execute a build. The custom styles and scripts will be integrated into the skin files.
Post build events offer a practical solution to extend the customization capabilities of Flareβs Tripane skin, allowing for additional styling and functionality adjustments not provided by the default skin editor.
---
## Implementing a dynamic search dropdown in MadCap Flare
Here's a Javascript you can use to implement a dynamic search dropdown in Flare. Just save the script below in a file and include it in your Flare project, and then include the script in your template page, or any page where you want the dropdown to appear. You might need to adjust the CSS selector of the search input field based on your project's structure.
> **NOTE**
> Updated 2024-10-14: Added word highlighting.
> Updated 2024-08-12: Fixed the bug related to boolean operators.
> Updated 2024-05-20: Added a method to show the dropdown when the search input is focused.
```javascript
class SearchManager {
constructor() {
this.debounce = this.debounce.bind(this);
this.handleSearch = this.handleSearch.bind(this);
this.displayResults = this.displayResults.bind(this);
this.clearResults = this.clearResults.bind(this);
this.showFullResults = this.showFullResults.bind(this);
this.hideDropDown = this.hideDropDown.bind(this);
this.showDropDown = this.showDropDown.bind(this); // Add this line
this.init();
}
debounce(func, delay) {
let debounceTimer;
return function () {
const context = this;
const args = arguments;
clearTimeout(debounceTimer);
debounceTimer = setTimeout(() => func.apply(context, args), delay);
};
}
handleSearch() {
let searchQuery = document.querySelector('.main-section .search-bar > input').value.trim();
const invalidPattern = /(\"|\($|\b(AND|OR|NOT|NEAR)\b)$/i;
const openParenthesesCount = (searchQuery.match(/\(/g) || []).length;
const closeParenthesesCount = (searchQuery.match(/\)/g) || []).length;
if (invalidPattern.test(searchQuery) || openParenthesesCount !== closeParenthesesCount) {
console.warn("Invalid search query. Please ensure proper use of operators and matching parentheses.");
return;
}
if (searchQuery.length > 0) {
MadCap.SearchHelper.SearchPane.Search(searchQuery, { searchContent: true })
.then(this.displayResults)
.catch(error => {
console.error("Search failed: ", error);
});
} else {
this.clearResults();
}
}
displayResults(results) {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.style.visibility = "visible"; // Ensure the dropdown is visible
dropdown.innerHTML = '';
const searchQuery = document.querySelector('.main-section .search-bar > input').value.trim(); // Get the current search query
results.content.slice(0, 5).forEach(item => {
const resultItem = document.createElement('li');
const title = document.createElement('div');
title.classList.add('title');
title.textContent = item.Title;
resultItem.appendChild(title);
const preview = document.createElement('div');
preview.classList.add('preview');
preview.textContent = item.AbstractText;
resultItem.appendChild(preview);
resultItem.addEventListener('click', () => {
// Append ?Highlight={searchword} to the URL
const urlWithHighlight = `${item.Link}?Highlight=${encodeURIComponent(searchQuery)}`;
window.location.href = urlWithHighlight;
});
dropdown.appendChild(resultItem);
});
if (results.content.length > 5) {
const showAll = document.createElement('li');
showAll.textContent = 'Showing 5 results. For all results, press ENTER';
showAll.addEventListener('click', this.showFullResults);
// Append this first so it's at the top:
dropdown.insertBefore(showAll, dropdown.firstChild);
}
}
displayAllResults(results) {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.innerHTML = '';
const searchQuery = document.querySelector('.main-section .search-bar > input').value.trim(); // Get the current search query
results.content.forEach(item => {
const resultItem = document.createElement('li');
const title = document.createElement('div');
title.classList.add('title');
title.textContent = item.Title;
resultItem.appendChild(title);
const preview = document.createElement('div');
preview.classList.add('preview');
preview.textContent = item.AbstractText;
resultItem.appendChild(preview);
resultItem.addEventListener('click', () => {
// Append ?Highlight={searchword} to the URL
const urlWithHighlight = `${item.Link}?Highlight=${encodeURIComponent(searchQuery)}`;
window.location.href = urlWithHighlight;
});
dropdown.appendChild(resultItem);
});
}
clearResults() {
const dropdown = document.getElementById('searchResultsDropdown');
dropdown.innerHTML = '';
}
showFullResults() {
// Implementation for showing full results
}
hideDropDown(event) {
const searchResultsDropdown = document.getElementById('searchResultsDropdown');
if (!event.target.closest(".search-field")) {
searchResultsDropdown.style.visibility = "hidden";
}
}
showDropDown() { // Add this method
const searchResultsDropdown = document.getElementById('searchResultsDropdown');
searchResultsDropdown.style.visibility = "visible";
}
init() {
$(document).ready(() => {
const searchInput = document.querySelector('.main-section .search-bar > input');
searchInput.addEventListener('input', this.debounce(this.handleSearch, 300));
searchInput.addEventListener('focus', this.showDropDown); // Add this line
const dropdown = document.createElement('ul');
dropdown.id = 'searchResultsDropdown';
document.querySelector('.main-section .search-bar').appendChild(dropdown);
});
document.addEventListener("click", this.hideDropDown);
}
}
new SearchManager();
```
---
## A guide to Improvementsoft's plugins
## The Plugins That Actually Make Flare Better
If youβre using MadCap Flare and not taking advantage of these plugins, youβre leaving time and quality on the table. I built these tools to solve real problems technical writers run into every day. Hereβs the lineup:
---
### π§ **AI Helper Plugin**
You want to use ChatGPT or Microsoft Copilot without breaking your Flare projects? This oneβs for you. It converts content to Markdown and back while preserving structure, snippets, and variables. That means you can ask your AI to rewrite, summarize, or improve contentβthen slot it right back into Flare without cleanup hell.
π [More on the AI Helper](https://www.improvementsoft.com/ai-helper-plugin)
---
### π§Ή **Mad Quality Plugin**
Think of this as your automatic editor. It scans your project and flags broken structure, inconsistent terminology, and style guide violations. Saves you hours of boring manual checks and lets you focus on writing, not hunting down rogue capital letters.
π [More on Mad Quality](https://docs.improvementsoft.com/madquality-plugin/)
---
### π§Ύ **Markdown Plugin**
This one bridges the gap between Flare and developers. Import and export Markdown without losing structure or formatting. Great if youβre working with GitHub, dev teams, or any system that likes Markdown more than XML.
π [More on the Markdown Plugin](https://www.improvementsoft.com/markdown-plugin/)
---
### π¨ **Style Stack Plugin**
Tired of juggling 40 different classes just to make your content look decent? With this, you can apply multiple styles to a single elementβjust like in real-world CSS. Makes your stylesheet cleaner and your life easier.
π [More on Style Stack](https://www.improvementsoft.com/style-stack-plugin/)
---
### π **Kaizen Plugin** (Free)
This oneβs all about continuous improvement. It helps you identify and fix productivity leaks in your Flare workflow. Nothing fancyβjust practical tools to work smarter.
π [Get the Kaizen Plugin](https://www.improvementsoft.com/docs/Kaizen%20Plugin/)
---
### In short?
These plugins exist because Flare didnβt do enough out of the box. They make your docs cleaner, your process faster, and your work less annoying. If youβre writing for a living, you should be using tools that pull their weight.
Let me know if you want help setting any of them up.
---
## Flare Best Practices 50 Tips and Tricks
π§ Feeling overwhelmed in MadCap Flare? Youβre not alone.
Many tech writers jump into Flare excited to single-source everything, only to get buried in a maze of conditions, snippets, and scattered styles. The result? Bloated projects, inconsistent outputs, and a lot of rework.
Hereβs the good news: with a clear strategy, you can tame even the messiest Flare project.
## Planning and Authoring
* Plan your documentation structure before writing
* Use topic-based authoring for modular content
* Create and use consistent topic templates
* Write structured content with logical flow
* Avoid inline formatting; use CSS styles instead
* Name files clearly with lowercase and hyphens
* Keep topic titles and IDs descriptive and unique
* Use master pages for headers, footers, and layout
* Embrace single-sourcing principles to reduce duplication
* Create snippets for reusable content blocks
* Enable snippet suggestions to encourage reuse
* Use variables for short, repeatable text elements
* Choose inline snippets when formatting or media is involved
* Use snippet seed text as a template
* Share content between projects using global project linking
* Apply conditions to tailor content for different outputs
* Name conditions clearly and consistently
* Use nested snippets sparingly and test thoroughly
* Group variables into sets for flexible output switching
## Styling, TOC, and Output
* Set up a stylesheet early in your project
* Avoid CSS mistakes like overrides and clutter
* Use named classes for consistent formatting
* Use mediums to define output-specific styles
* Hide unused or deprecated styles
* Debug styles using the Style Inspector
* Add comments and organize your CSS for clarity
* Preview outputs regularly to verify styles and formatting
* Use the TOC to control what content gets published
* Create multiple TOCs for different outputs or users
* Use grid view to manage TOCs at scale
* Automatically generate TOCs for print outputs
* Insert index keywords for search/navigation support
* Organize index entries with parent/child relationships
* Use auto-indexing for repeated terminology
* Keep TOC entries in sync with condition tags
* Define one target per output type or variation
* Customize skins and page layouts per target
* Use batch targets to build multiple outputs together
* Review the build log for warnings and errors
* Clean the project before building to ensure accurate outputs
* Use alias IDs for context-sensitive help
* Set up publishing destinations ahead of time
* Use command-line tools for automation
## Organization and Collaboration
* Use logical folders to organize your content
* Store assets in the Resources folder
* Standardize naming conventions across your team
* Use parent-child project models for shared content
* Run reports to clean up unused files
* Use project notes to document rules and structure
* Bind your project to Git or another VCS
* Commit and pull often to reduce conflicts
* Use branches for large changes or experiments
* Exclude output and temporary files from version control
* Document your source control workflow for others
## QA, Accessibility, and Productivity
* Build frequently to catch issues early
* Use Analyzer reports for style and usage checks
* Run clean builds to rule out leftover files
* Use divide-and-conquer to isolate build issues
* Review and act on all build warnings
* Test all output targets to ensure consistency
* Use headings and semantic tags for accessibility
* Add alt text to all non-decorative images
* Use proper table headers for screen readers
* Enable accessibility features in output settings
* Test with a screen reader or keyboard navigation
* Learn and use keyboard shortcuts for efficiency
* Use Find in Files to locate terms globally
* Use File List filters to manage content by type
* Pin frequently used styles and snippets
* Save and switch between custom UI layouts
* Record macros for repetitive tasks
* Use bookmarks to navigate long topics
* Use annotations for internal notes and review feedback
## Plugins and Automation
* Use the Kaizen Plugin for batch cleanup and markdown support
* Use the Mad Quality Plugin for editorial rule enforcement
* Use the AI Helper Plugin to interact with AI tools safely
---
## A Practical AI Workflow for MadCap Flare
Everyone's using AI for writing now. But if you work in MadCap Flare, you've probably noticed the gap: AI generates great drafts, but getting that content *into* Flare without breaking everything is a different story. Variables become plain text. Snippet references disappear. Styles don't match your stylesheet.
Here's a workflow that actually works β one that uses AI for speed while keeping your Flare architecture intact.
## The problem with copy-paste
The most common AI workflow in technical writing looks like this:
1. Open ChatGPT (or Claude, or Copilot)
2. Ask it to write or rewrite content
3. Copy the response
4. Paste it into Flare
5. Spend 20 minutes fixing formatting, re-applying variables, and restoring structure
Step 5 is where the productivity gain evaporates. AI saves you 10 minutes of drafting and costs you 20 minutes of cleanup. The net result is slower than writing it yourself.
The root cause: AI doesn't know about your Flare architecture. It doesn't know that "Product Name" should be a variable, or that the warning block should be a snippet, or that your H2s use a custom class.
## A better approach: Flare-aware Markdown
The fix is to give AI your content in a format that preserves Flare-specific elements, and then convert the AI's response back into proper Flare XHTML.
With the [AI Helper Plugin](/ai-helper-plugin), the workflow becomes:
### Step 1: Export from Flare as Markdown
Use **Copy Topic (MD)** to convert your Flare topic to Markdown. The plugin preserves:
- Variables as `{{VariableSet.VariableName}}` tokens
- Snippet references as `[snippet:path/to/snippet.flsnp]` markers
- Heading levels and list structures
- Table formatting
### Step 2: Send to AI with context
Paste the Markdown into your AI tool along with your prompt. Because variables and snippets are preserved as tokens, the AI knows to leave them in place. You can ask it to:
- Rewrite for a different audience
- Simplify the language
- Add sections
- Restructure the flow
The AI works with the content while respecting the structural markers.
### Step 3: Import back into Flare
Use **Replace Selection** or **Replace Topic** to paste the AI's Markdown response back. The plugin:
- Converts Markdown headings to Flare's heading classes
- Restores variable tokens to actual `` elements
- Restores snippet markers to proper `` references
- Applies your configured class mappings
No manual reformatting. The structure survives the round-trip.
## Working at scale: Search & Compile
For larger tasks β like rewriting an entire section or analyzing content across multiple topics β use **Search & Compile**:
1. Search for topics by keyword or folder
2. Select the topics you need
3. Compile them into a single Markdown document
This gives you a comprehensive view of related content that you can send to AI for analysis, consistency checking, or batch rewriting. When you're done, split the result back into individual topics using the **Split by H1/H2/H3** commands.
## Practical tips
**Configure your class mappings.** In the plugin options, set up how Markdown elements map to your Flare classes. If your bold text uses a `strong-emphasis` class instead of default ``, configure that once and every import respects it.
**Use templates for common prompts.** The plugin's template system lets you save and reuse prompts. Create templates for your common tasks: "Simplify for end users", "Add troubleshooting steps", "Convert to procedure format".
**Start with non-critical content.** Test the workflow on internal documentation or draft content before using it on production topics. This builds confidence in the round-trip process.
**Review the diff.** After importing AI content, use Flare's track changes or a diff tool to verify what changed. AI occasionally makes subtle structural changes that are easy to miss.
## The net result
With this workflow, AI becomes a genuine productivity multiplier for Flare authors:
- **Drafting** goes from hours to minutes
- **Rewriting** preserves all structural elements
- **Analysis** works across topics, not just within them
- **Quality** stays consistent because the architecture is never broken
The key insight is that AI doesn't need to understand Flare β it just needs content in a format that preserves the structure. The plugin handles the translation in both directions.
[Try the AI Helper Plugin](/ai-helper-plugin) with a free 14-day trial.
---
## Why Your Flare Project Slows Down After 500 Topics
Every Flare project starts fast. Fifty topics, a few conditions, a handful of variables β everything works. Then you cross 500 topics and things start to feel different. Builds take longer. Finding content takes more clicks. New writers take weeks to become productive. The project didn't break β it just wasn't designed for the load it's carrying.
Here's why it happens and what you can do about it.
## The structural debt pattern
Most Flare projects grow organically. You add topics as products ship. You create conditions when someone needs a new output variant. You add snippets when someone notices duplicated content. Each decision makes sense in the moment.
But these decisions compound. By the time you hit 500+ topics, you're dealing with:
- **Flat folder structures** where everything lives in one or two directories
- **Condition sprawl** where nobody can confidently say which conditions affect which output
- **Variable files** that have grown into grab-bags of unrelated values
- **TOC structures** that mirror org charts instead of user tasks
- **Snippet libraries** that nobody trusts because they don't know what else references them
None of these are bugs. They're structural debt β the accumulated cost of growing without an architecture.
## Why it feels like Flare is the problem
When a project slows down, the first instinct is to blame the tool. "Flare is slow." "The build takes too long." "The XML editor is fighting me."
But in most cases, the slowdown isn't Flare β it's what's inside the project. Flare is processing exactly what you told it to process. If your build includes 200 topics that aren't needed in the output because conditions are tangled, Flare still has to evaluate every one of them.
The same applies to authoring speed. If a writer has to open 30 folders to find the right snippet, or guess which condition tag to apply, the tool isn't slow β the structure is unclear.
## What scales and what doesn't
After working with dozens of Flare projects ranging from 200 to 10,000+ topics, here's what I've seen consistently:
### Scales well
- **Flat snippet libraries with clear naming** β `warning-electrical-hazard.flsnp` instead of `snippet_47.flsnp`
- **Condition tags organized by output type**, not by internal team structure
- **Variable files grouped by domain** β product names in one file, UI labels in another
- **Folder structures that mirror the TOC**, not the authoring workflow
- **Topic templates** that enforce consistent heading structures
### Breaks at scale
- **Snippets nested inside snippets** β debugging becomes exponentially harder
- **Conditions applied at the paragraph level** across hundreds of topics
- **One monolithic variable file** with 300+ entries
- **Mixed concerns in TOCs** β navigation structure tangled with output filtering
- **No naming conventions** β every writer names files differently
## Practical fixes
You don't need to rebuild the project from scratch. The highest-impact changes are often structural reorganizations that don't touch the content itself:
**1. Audit your conditions.** Export a condition usage report and identify which conditions are actually used in which targets. Remove or consolidate the rest. Most projects have 30-40% unused conditions.
**2. Split your variable files.** Group variables by purpose: product identifiers, version numbers, UI strings, company information. This makes maintenance predictable.
**3. Restructure folders to match your TOC.** When the file system mirrors the information architecture, writers find content faster and file names become self-documenting.
**4. Create topic templates.** A template that enforces "H1 β intro paragraph β H2 sections" costs nothing to create and saves hours of reformatting.
**5. Document your conventions.** A one-page guide that says "conditions are for output targets, not content visibility" prevents the next round of structural debt.
## When to get help
If your project has grown past the point where these fixes are straightforward β if conditions are deeply entangled, if snippets reference other snippets in chains, if nobody is confident about what a build actually produces β that's when an external architecture review pays for itself.
I've done this for teams at companies like Tetra Pak, SimCorp, and Philips. The pattern is always the same: understand the current structure, identify the highest-impact changes, and implement them in a way that doesn't disrupt ongoing authoring.
[Book a 30-minute call](/about) to discuss your project, or [run the free Flare Diagnosis](/flare-bottleneck-diagnosis) to see where your bottlenecks are.
---
## The MadCap Flare Bottleneck Diagnosis: 5 Factors That Predict Project Failure
Most Flare projects that fail do not fail suddenly. They degrade over months or years until authoring is painful, builds are unpredictable, and nobody trusts the output. The good news is that the failure patterns are consistent and detectable. Five structural factors predict whether a Flare project is heading toward trouble β and all five are measurable before things break.
## Why diagnosis matters more than symptoms
Teams usually describe their problems in terms of symptoms. "Builds are slow." "Onboarding takes too long." "We keep finding errors in published output." These are real problems, but treating symptoms without understanding root causes leads to fixes that do not last.
A writer who complains about slow builds might be working in a project where condition logic forces Flare to evaluate thousands of unnecessary topics. Fixing the build configuration will not help. The bottleneck is structural, and until you address the structure, the symptom will keep returning in different forms.
The five factors below are not symptoms. They are structural conditions that reliably predict whether a project will scale or stall. Each one can be assessed independently, and each has a clear remediation path.
## Factor 1: Condition complexity
Conditions are the most powerful feature in Flare β and the most dangerous when they grow unchecked. A project with 10 condition tags and clear output targets is maintainable. A project with 80 condition tags, nested conditions, and conditions applied at the paragraph level inside topics is a project where nobody fully understands what any given build will produce.
The warning signs are specific. When writers apply conditions by guessing or copying what they see in similar topics, rather than following a documented scheme, condition logic has outgrown human comprehension. When build outputs contain content that should have been excluded, or exclude content that should have been included, the condition system has become unreliable.
The measurable threshold is straightforward: if your team cannot produce a complete, accurate matrix of which conditions apply to which targets without auditing the project, condition complexity has crossed the line from useful to hazardous.
## Factor 2: Content architecture debt
Content architecture is how topics, snippets, variables, and TOCs relate to each other. In a well-architected project, these relationships are intentional and documented. In a project carrying architecture debt, they are accidental and opaque.
Architecture debt accumulates through organic growth. A writer creates a snippet for reuse in two topics. A year later, that snippet is referenced in forty topics and contains conditions of its own. Another writer creates a second snippet that covers similar content because they could not find the first one or were not sure it was safe to modify.
The result is a dependency graph that nobody can visualize. Changing a snippet might affect three topics or three hundred. Renaming a variable file might break targets that nobody remembers exist. Architecture debt does not slow things down linearly β it creates compounding risk where every change requires increasingly conservative testing.
## Factor 3: Authoring friction
Authoring friction measures how much effort a writer expends on project mechanics versus actual content creation. In a healthy project, most of a writer's time goes to researching, writing, and reviewing content. In a high-friction project, writers spend significant time navigating folder structures, searching for the right snippet, figuring out which condition to apply, or reformatting content because templates are missing or inconsistent.
The impact of authoring friction extends beyond productivity. High friction drives inconsistency because writers develop personal workarounds. One writer might avoid snippets entirely because they find them unreliable. Another might create inline content instead of using variables because the variable file is too large to search efficiently. Each workaround increases structural debt, which increases friction for the next writer.
You can measure authoring friction by timing how long it takes a competent writer to create a standard topic type from scratch, including all the structural elements like conditions, snippets, and variables. If that number is more than double the time spent on the writing itself, friction is a bottleneck.
## Factor 4: Build and output reliability
A reliable build produces the expected output every time, with no manual intervention. An unreliable build requires someone to check the output, fix errors, rebuild, or apply workarounds to get a clean result.
Build reliability degrades gradually. The first sign is usually warnings in the build log that get ignored because the output "looks fine." Then edge cases appear: a topic missing from one target but not another, a broken link that only manifests in one output format, an image that renders in the browser preview but not in the PDF. Each of these is minor in isolation. Collectively, they mean the build process is no longer trustworthy.
The downstream cost is significant. When builds are unreliable, teams add manual QA steps after every build. Those steps consume time, and they introduce human variability β the reviewer catches some errors but misses others. Published documentation quality becomes inconsistent, and the team loses confidence in the toolchain.
## Factor 5: Knowledge concentration risk
Knowledge concentration measures how dependent the project is on specific individuals. In every Flare project, some tribal knowledge exists. But when only one person understands the condition scheme, or only one person knows how the build targets are configured, or only one person can troubleshoot snippet inheritance β that is a single point of failure.
Knowledge concentration is the hardest factor to measure because the people who hold the knowledge rarely recognize it as a risk. They see it as experience. But experience that is not documented and not transferable is organizational risk. When that person goes on leave, changes roles, or leaves the company, the project becomes fragile overnight.
The test is simple: could your team maintain and extend the project if any single person were unavailable for three months? If the honest answer is no, knowledge concentration is a bottleneck.
## How the five factors interact
These factors do not operate in isolation. High condition complexity increases authoring friction. Architecture debt reduces build reliability. Knowledge concentration prevents remediation of all the other factors because the person who understands the problems is the same person who is too busy maintaining the project to fix them.
This interaction pattern is why incremental fixes often fail. Fixing conditions without addressing architecture debt just moves the problem. Reducing authoring friction without documenting knowledge does not survive staff changes. Effective remediation requires understanding the full picture first, then prioritizing changes based on which factors are driving the most damage.
## Take the diagnosis
The [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) is a free assessment that evaluates your project against all five factors. It takes a few minutes to complete, gives you a clear picture of where your bottlenecks are, and identifies which improvements will have the highest impact. No sales call required β just a structured way to see what is actually holding your project back.
---
## Why MadCap Flare Migrations Fail β And How to Make Yours the Exception
Roughly 80% of MadCap Flare migrations run over budget, over schedule, or deliver a project that is harder to maintain than the system it replaced. That is not because Flare is the wrong tool. It is because the migration was treated as a conversion project when it should have been treated as an architecture project.
## The conversion trap
The most common approach to a Flare migration looks like this: export content from the legacy system, import it into Flare, fix the formatting errors, and declare the migration complete. Tools exist to automate parts of this process, and they work β in the narrow sense that content ends up inside a Flare project.
The problem is that converted content carries the structural assumptions of the source system. If your legacy content was written for a linear document format, you now have a Flare project full of topics that assume linear reading order. If your source system had no reuse model, you now have hundreds of standalone topics with duplicated content baked into each one. If terminology was inconsistent in the source, it is still inconsistent after conversion.
A migration that only converts format without addressing structure gives you a new tool wrapped around an old architecture. Within six months, every problem you had in the old system reappears in the new one, plus new problems created by the mismatch between Flare's architecture model and your content's actual structure.
## Structural mistake 1: No information architecture before migration
Flare is built around a specific content model: topics, snippets for reuse, variables for substitution, conditions for output filtering, and TOCs for navigation. These are architectural decisions that should be made before any content is migrated β not discovered afterward.
Yet most migration plans skip directly to "move the content." Teams import thousands of pages and then try to impose structure retroactively. Retroactive restructuring is three to five times more expensive than designing the architecture upfront, because every change requires re-testing outputs and verifying that nothing broke.
Before migrating a single topic, you need clear answers to these questions: What are your output targets? What content is shared across targets and what is unique? What terminology must be controlled? How will topics be organized β by product, by task, by audience? These decisions define your Flare project structure. Making them after migration means rebuilding what you just built.
## Structural mistake 2: Migrating everything
Legacy systems accumulate content over years. Feature descriptions for deprecated products. Procedures for workflows that no longer exist. Duplicate topics created because nobody could find the original. Version-specific content that is no longer relevant.
The instinct is to migrate everything and sort it out later. This is the second most expensive mistake in Flare migrations. Every obsolete topic that enters the new project adds maintenance overhead. It clutters search results. It confuses condition logic. It inflates build times. And "sort it out later" almost never happens because new work always takes priority over cleanup.
A content audit before migration is not optional. Categorize every piece of source content as migrate, merge, archive, or delete. This is tedious work, and it requires subject matter expertise. It is also the single highest-ROI activity in any migration project, because every piece of content you do not migrate is content you never have to restructure, maintain, or troubleshoot in Flare.
## Structural mistake 3: Ignoring the reuse model
Content reuse is one of the primary reasons teams move to Flare. But reuse does not happen automatically. It requires identifying content that should be shared, creating snippets or variables, and establishing conventions for when to use each mechanism.
The mistake is migrating content first and trying to "add reuse later." By the time 2,000 topics are in the project, identifying reuse opportunities means comparing every topic against every other topic. The same safety warning written slightly differently in forty topics. The same product description with minor variations in thirty topics. The same procedure with two different step orderings in fifteen topics.
Retrofitting reuse at this scale is a major project in itself β often as expensive as the original migration. The alternative is to define your reuse strategy before migration, identify candidates during the content audit, and create the snippet and variable infrastructure as part of the migration process, not after it.
## Structural mistake 4: No style guide enforcement from day one
Migrations involve bulk content processing. Whether done manually or with automated tools, the result is content that may be structurally valid but stylistically inconsistent. Heading conventions vary. Terminology differs between topics. List formatting is mixed. Paragraph styles from the source system get mapped to arbitrary Flare classes.
If you do not enforce style standards during migration, inconsistency becomes the baseline. Every topic authored after migration inherits whatever conventions the writer observes in existing content β which is now inconsistent content. The style guide might specify one approach, but the project demonstrates another.
Automated style enforcement during or immediately after migration prevents this compounding effect. When a quality gate catches inconsistencies before they reach the main project, writers learn the correct conventions from day one. Without that gate, you are planning a future cleanup project that will cost multiples of what enforcement would have cost.
## Structural mistake 5: Treating migration as a one-time event
A migration project has a start date and an end date. Content architecture does not. The decisions you make during migration β folder structure, condition scheme, reuse model, naming conventions β need to survive years of ongoing authoring by people who were not involved in the migration.
Teams that treat migration as a one-time event do not document their architectural decisions. They do not create templates. They do not establish governance processes. The migration team finishes, hands over the project, and the writers who inherit it gradually drift from the intended structure because nobody told them the rules.
Six months later, the project looks nothing like what was designed. Conditions have proliferated. New folder structures have appeared. Snippets are being duplicated instead of reused. The migration "succeeded" in the sense that content was moved, but the architecture has already begun to decay.
## What a successful migration looks like
Migrations that succeed share a common pattern. They invest heavily in the planning phase β content audit, information architecture, reuse model, style guide, and governance plan β before any content moves. The actual content migration is the shortest phase of the project, not the longest.
They also treat the migration as the foundation for ongoing authoring, not an isolated project. Templates, conventions, and automated enforcement are in place before writers start working in the new system. Architectural decisions are documented and accessible to everyone, not locked in one person's head.
The result is a Flare project that scales cleanly from the start, where every writer produces consistent output, and where adding new content makes the project more valuable instead of more fragile.
If you are planning a Flare migration β or recovering from one that did not go as expected β the first step is understanding your current structural position. The [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) evaluates the factors that determine whether a migration will scale or stall, and it is free. For hands-on migration architecture and execution, [get in touch](/contact).
Migrating from Word specifically? The complete process is published free as the [47-step Word to MadCap Flare migration checklist](/guides/word-to-flare-migration-checklist) β printable, no email required.
---
## The Hidden Cost of Manual QA in Technical Documentation
Your reviewers are doing their best. The problem is not effort. The problem is that manual QA fundamentally cannot scale with content volume.
## The Math: What Manual QA Actually Costs
Let's make the hidden cost visible.
A typical style guide has between 50 and 200 active rules. These include terminology preferences, heading conventions, sentence structure guidelines, and more. A reviewer checking a single topic against those rules needs 15 to 30 minutes for a thorough review. That is for one topic.
Now scale it. A team producing 20 topics per week needs 5 to 10 hours of review time weekly just for style guide compliance. That does not include technical accuracy review, SME review, or any rework cycles. For larger teams producing more than 50 topics per week, review becomes a full-time job for one or more people.
But hours are only part of the cost. The bigger number is the rework cycle. When a reviewer catches issues two weeks after the writer created the topic, the writer has to switch context, understand the feedback, make corrections, and resubmit. Studies on code review, which follows similar dynamics, show that delayed feedback costs 3 to 5 times more to resolve than immediate feedback.
Multiply the direct review hours by the rework multiplier and the true cost of manual QA is typically 2 to 3 times what teams estimate. For a 10-person writing team, that can easily equal 1 to 2 full-time positions consumed by the review process.
## Why Manual QA Does Not Scale
Even with unlimited reviewer hours, manual QA has structural limitations that make it unreliable at scale.
**Reviewer inconsistency.** Different reviewers catch different issues. Reviewer A focuses on terminology. Reviewer B focuses on structure. Reviewer C catches formatting problems but misses style violations. The same topic reviewed by three people produces three different sets of feedback. Your quality standard becomes whatever that reviewer notices, not what the style guide requires.
**Batch versus continuous review.** Manual review happens in batches after the topic is written, often after several topics are queued. This creates two problems. Feedback is delayed, which increases rework cost. Reviewers also experience cognitive fatigue from reviewing multiple topics in sequence, which decreases catch rates. The last topic in a review batch receives less attention than the first.
**Style guide drift.** Style guides evolve. New rules are added. Old rules are reinterpreted. The reviewer's mental model of those rules updates slowly and unevenly. Six months after a style guide update, some reviewers enforce the new rules, some still apply the old ones, and some rely on personal interpretation. The gap between the documented standard and the enforced standard widens over time.
**The 80/20 trap.** Most reviewers catch obvious violations, especially the ones they have seen repeatedly. The remaining 20 percent, including unusual constructions, edge-case rules, and cross-topic inconsistencies, slip through consistently. Across thousands of topics, that 20 percent becomes significant inconsistency in published documentation.
## What "Good Enough" Quality Actually Costs
Teams that accept the limits of manual QA often settle for "good enough" quality. The style guide exists. Reviewers do their best. Some inconsistency is accepted as the cost of doing business.
But "good enough" creates downstream costs that rarely get traced back to QA.
**Customer trust erosion.** Inconsistent terminology confuses users. When the same feature has three different names across documentation, users lose confidence in everything else. Support tickets increase not because the content is wrong, but because users cannot trust that it is right.
**Support ticket volume.** Documentation inconsistency is a major driver of support contacts. When users encounter contradictory instructions or ambiguous terminology, they contact support for clarification. Every support ticket has a cost, typically between 15 and 50 dollars for technical products. Even a small percentage of tickets caused by documentation inconsistency can create significant annual expense.
**Translation inflation.** Translation memory works by matching identical segments. When the same concept is expressed differently across topics, even with slight wording changes, each variation becomes a separate translation segment. Inconsistent source content directly inflates translation costs. Organizations localizing into five or more languages often find that 10 to 20 percent of their translation budget pays for inconsistency in the source language.
**Compounding debt.** Every inconsistent topic that ships becomes a precedent for the next writer who references it. Inconsistency breeds more inconsistency. Without automated enforcement, baseline quality drifts downward over time and requires increasingly expensive cleanup efforts.
## The Approach That Scales: Automated Quality Gates
The alternative to manual QA is not eliminating QA. It is moving enforcement from people to systems. Automated quality gates encode style guide rules into the authoring workflow so violations surface while writers are working, not weeks later during review.
Here is what changes.
**Immediate feedback.** Writers see violations while authoring. The rework cost drops from three to five times the original effort to nearly zero because the writer remains in context. This alone often recovers more time than the manual review process consumes.
**Consistent enforcement.** Automated rules do not vary by mood or preference. Every topic is checked against every rule every time. The gap between documented standards and enforced standards effectively disappears.
**Scalable coverage.** Adding another 100 topics does not increase review hours. Automated checks run in seconds regardless of project size. Quality scales with content volume instead of requiring proportional reviewer headcount.
**Reviewers focus on what matters.** When mechanical style enforcement is automated, human reviewers can focus on technical accuracy, clarity, information architecture, and user experience. Review quality improves because attention shifts from commas and terminology to meaning and structure.
**Measurable quality.** Automated rules generate data. Teams can track compliance rates, identify frequently violated rules, and measure the impact of training and process improvements. Quality becomes measurable and manageable rather than assumed.
The transition does not need to be all or nothing. Start with the 20 rules that create the most rework. Automate those. Measure the impact. Expand from there. Most teams see meaningful time savings within the first month.
The [Mad Quality Plugin](/madquality-plugin) brings automated quality gates directly into MadCap Flare β check it out to see how it works in practice.
---
## Why Your Documentation Will Break Your AI Implementation
Enterprise AI projects are failing at a remarkable rate, and the usual suspects β model selection, prompt engineering, integration complexity β get all the attention. But there is a quieter, more fundamental problem that undermines AI initiatives before they produce a single useful answer: the documentation that AI is supposed to learn from is not structured well enough for AI to use.
## The assumption that breaks everything
Every AI implementation that involves company knowledge β customer-facing chatbots, internal knowledge assistants, support automation, RAG-based search β starts with the same assumption: we have documentation, so we can feed it to the AI.
That assumption hides a critical gap. Having documentation and having documentation that AI can reliably interpret are two different things. Most enterprise documentation was written for humans reading in a browser. Humans are remarkably good at compensating for structural problems. They infer meaning from context. They recognize that "Dashboard," "Control Panel," and "Home Screen" probably mean the same thing. They skip navigation elements, sidebars, and boilerplate without conscious effort.
AI models do none of this. They process exactly what they receive. If your documentation contains structural noise, terminological inconsistency, or missing context, the AI will either hallucinate to fill the gaps or produce answers that are technically wrong in ways that are difficult to detect.
## Problem 1: Structural noise
Most documentation output formats mix content with presentation. HTML help systems include navigation frames, breadcrumb trails, cookie consent banners, JavaScript widgets, and layout markup. When an AI model ingests a page, it cannot reliably distinguish the actual content from the surrounding chrome.
The result is that AI context windows β the limited amount of text a model can process at once β get filled with noise. A 4,000-token page might contain 2,500 tokens of actual content and 1,500 tokens of navigation, headers, footers, and scripts. The model is spending 37% of its capacity on content that actively degrades answer quality.
At scale, this problem compounds. A RAG system that retrieves five relevant pages now has five pages worth of structural noise competing with five pages of actual content. The signal-to-noise ratio drops to the point where the model's answers become unreliable, and no amount of prompt engineering can compensate for polluted input.
## Problem 2: Terminological inconsistency
When the same concept has multiple names across your documentation, AI models have no reliable way to connect them. A user asks about "configuring the dashboard." Your documentation has relevant content under "setting up the control panel" and "customizing the home screen." A human reviewer would immediately recognize these as relevant. An AI model might retrieve none of them, or retrieve one and miss the others.
This is not a theoretical concern. In testing across enterprise documentation sets, terminological inconsistency is the single largest source of retrieval failures in RAG systems. The content exists. The AI simply cannot find it because the vocabulary does not match.
The problem gets worse with product-specific terminology. Feature names that changed between versions. Internal code names that leak into documentation. Regional variations in terminology. Each inconsistency is a potential retrieval failure, and in a documentation set with thousands of topics, these failures are pervasive.
## Problem 3: Missing metadata and structure
AI models rely on structural signals to understand content. Headings indicate topic hierarchy. Metadata descriptions summarize what a page covers. Consistent heading levels (H1, then H2, then H3) communicate the logical structure of information.
When documentation lacks proper structure β when headings are used for visual formatting rather than semantic hierarchy, when metadata descriptions are missing or auto-generated from the first sentence, when list items are formatted as paragraphs with manual bullet characters β the AI loses its ability to parse content reliably.
This matters most during retrieval. When a system needs to decide which content chunk is most relevant to a question, it relies on structural signals. A well-structured topic with accurate metadata and clear heading hierarchy is easy to chunk, index, and retrieve. A poorly structured topic that reads as a wall of text with inconsistent formatting produces chunks that overlap, miss context, or retrieve irrelevant content.
## Problem 4: Unresolved dynamic content
Authoring tools like MadCap Flare support dynamic content features β conditional tags, glossary popups, expandable sections, dropdown text, and toggle visibility. These features work well in a browser where JavaScript handles the interaction. They work poorly or not at all when AI processes the output.
Conditional content that is not resolved before AI ingestion means the AI receives content tagged for audiences it should never see. Glossary terms that only appear on hover are glossary terms the AI never encounters. Expandable sections that require a click to reveal are sections that do not exist in the AI's version of the content.
The gap between what a human sees in the browser and what an AI processes from the same output can be substantial. Teams are often surprised to discover that 10-20% of their content is effectively invisible to AI because it lives behind interactive elements that only render in a browser context.
## Problem 5: No discoverability layer
Even when individual pages are well-structured, AI needs a way to find relevant content without crawling everything. A human navigates documentation through tables of contents, search, and links. An AI needs a machine-readable index that describes what exists, where it lives, and how topics relate to each other.
Without a discoverability layer β a sitemap, an llms.txt file, or a structured API β AI systems fall back to brute-force search. They either load too much content and exhaust context limits, or they load too little and miss critical information. Both outcomes produce unreliable answers.
The llms.txt standard was designed specifically for this problem. It provides a structured, machine-readable index of documentation that AI models can use to efficiently locate relevant content. Implementing it is a small effort with outsized impact on AI retrieval quality.
## The fix is structural, not technical
The common response to AI quality problems is to adjust the AI β tune the model, refine the prompts, tweak the retrieval parameters. These are valid optimizations, but they are optimizations on top of a broken foundation. If the input content is noisy, inconsistent, and poorly structured, no amount of AI-side tuning will produce reliable results.
The fix is to address the documentation itself. Clean the structure. Enforce terminology. Add metadata. Resolve dynamic content. Create a discoverability layer. These improvements make the documentation better for every consumer β human readers, search engines, translation systems, and AI models alike.
For teams working in MadCap Flare, the [AI Helper Plugin](/ai-helper-plugin) addresses these problems directly. It generates clean Markdown output from Flare topics, creates llms.txt indexes from your build output, and provides a round-trip workflow for AI-assisted authoring that preserves your content architecture. If your AI initiative depends on documentation quality, [start with the content](/ai-helper-plugin).
---
## RoboHelp to MadCap Flare: What Actually Breaks (And How to Fix It Before You Start)
Every RoboHelp to Flare migration looks straightforward on paper. Flare even has a built-in RoboHelp import wizard. But the projects that come out the other side almost always need significant cleanup, and the problems are predictable if you know where to look.
## Why the import wizard is not enough
Flare's RoboHelp import gets you 70 to 80 percent of the way. It converts topics to XHTML, brings in your TOC structure, and maps most basic formatting. That last 20 to 30 percent is where teams lose weeks.
The wizard handles syntax conversion. It does not handle architectural translation. RoboHelp and Flare model content differently at a structural level, and those differences create silent problems that surface months later when you try to build, reuse, or scale.
## Structural differences that matter
### Conditional content
RoboHelp uses conditional build tags that work as simple include/exclude filters. Flare uses condition tags too, but with a more granular model: conditions can be applied at the topic, paragraph, span, and even attribute level, and they interact with targets through include/exclude/undefined logic.
When you import, RoboHelp's build tags come in as Flare condition tags. But the mapping is flat. If your RoboHelp project used build tags for multiple purposes β audience filtering, product variants, and output type control β those all land in a single condition tag set in Flare. Untangling them after import is tedious. Rearchitecting them before import saves significant time.
### Stylesheets
RoboHelp projects typically use a mix of inline styles, CSS classes, and RoboHelp-specific formatting. The import brings the CSS over, but it often arrives bloated with duplicate selectors, browser-specific hacks from older RoboHelp versions, and styles that have no equivalent in Flare's stylesheet model.
The practical impact: your Flare project starts with a stylesheet that is 3 to 5 times larger than it needs to be, filled with rules that conflict with Flare's default behavior. Writers apply styles that look correct in the editor but render differently in the output.
### TOC and browse sequences
RoboHelp TOCs import into Flare TOCs, but the relationship between TOCs and targets works differently. In RoboHelp, you typically have one TOC per output. In Flare, multiple targets can share a TOC, and TOCs can reference other TOCs. The import creates a one-to-one mapping that misses opportunities for reuse and often duplicates navigation structures.
### Variables and snippets
RoboHelp user-defined variables import cleanly. But RoboHelp does not have a snippet equivalent with the same flexibility as Flare's snippet system. Content that was copy-pasted across topics in RoboHelp β which is common because RoboHelp's reuse options are limited β stays duplicated in Flare. You now have a reuse tool but duplicated content that should be using it.
### Index keywords and search
RoboHelp index keywords import into Flare, but Flare handles search differently. RoboHelp's search configuration, synonyms, and excluded words do not transfer. If your users depend on search, you need to rebuild the search configuration from scratch.
## What breaks silently
The worst migration problems are the ones that do not produce errors. Everything imports. Everything builds. But the output has issues that only surface during review or, worse, after publishing.
**Image paths.** RoboHelp and Flare handle image references differently. Imports often create references that resolve in the editor but break in specific output types, especially PDF targets.
**Cross-references.** RoboHelp hyperlinks between topics come in as basic anchor links. Flare's cross-reference system, which automatically updates link text and tracks broken references, is not used. You have working links with none of Flare's link management benefits.
**Master pages and layouts.** RoboHelp's master page concept does not align with Flare's master page model. The import does not create Flare master pages. Your topics arrive without the layout framework that Flare outputs depend on.
**Character encoding.** Older RoboHelp projects sometimes contain non-standard character encoding, especially in projects that were upgraded through multiple RoboHelp versions. These characters import without errors but render as garbled text in specific output formats.
## Pre-migration checklist
Before you run the import wizard, work through this list. Each item takes minutes to check and can save days of post-migration cleanup.
1. **Inventory your conditions.** List every build tag and what it controls. Group them by purpose: audience, product, output type, or temporary flags. Plan your Flare condition tag architecture before import.
2. **Clean your stylesheet.** Remove unused styles, inline formatting, and RoboHelp-specific CSS. The cleaner your source CSS, the cleaner the import.
3. **Audit cross-references.** Identify all topic-to-topic links. Decide which should become Flare cross-references versus which should remain hyperlinks.
4. **Identify reuse candidates.** Find content duplicated across topics. Plan which pieces become Flare snippets. It is far easier to create the snippet architecture during migration than to retrofit it later.
5. **Test with a subset.** Import 20 representative topics first. Build every target type you need. Review the output carefully. The problems you find in 20 topics will be the same problems across 2,000.
6. **Document your mappings.** Create a mapping document that records how each RoboHelp element translates to its Flare equivalent: conditions, styles, variables, and file structure.
## The cost of skipping preparation
Teams that run the import wizard without preparation typically spend 2 to 4 weeks on post-migration cleanup for a project with 500 or more topics. Teams that invest 3 to 5 days in pre-migration planning and source cleanup cut that to a few days.
The difference is not about the import tool. It is about understanding the structural gap between the two platforms and closing that gap before the content crosses over.
If your Flare project already went through a rough migration and is carrying structural debt from its RoboHelp origins, [run the free Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) to identify the highest-impact areas to fix first. For scope and pricing on a hands-on engagement, see our [RoboHelp to MadCap Flare migration](/madcap-flare-migration/robohelp/) page, the broader [MadCap Flare migration services](/madcap-flare-migration/) page, or the strategy view on [MadCap Flare conversion](/madcap-flare-conversion/).
---
## Is Your Flare Project Heading for a Rebuild? Five Warning Signs
Not every struggling Flare project needs a rebuild. Most can be improved incrementally with targeted structural changes. But some projects reach a point where incremental fixes are no longer viable β where the architecture itself has become the constraint. Here are five warning signs that your project has crossed that line.
## Warning sign 1: Nobody trusts the conditions
Every Flare project uses conditions. In a healthy project, conditions follow a clear logic: this condition controls the audience, that one controls the output format, these conditions map to product variants. Any writer can look at a condition tag and know what it does.
In a project heading for a rebuild, conditions have become opaque. Writers apply conditions based on habit or by copying what they see in neighboring topics. Nobody can explain the full condition logic for any given target without spending 30 minutes tracing dependencies. Conditions overlap in meaning. Some conditions are used in three topics. Others are applied to hundreds of topics but excluded from every target.
The symptom is easy to spot: ask three writers what a specific condition tag does, and you get three different answers. Or ask which conditions a specific target needs, and nobody can answer without opening the target settings and cross-referencing with topic-level conditions.
When conditions are this tangled, fixing them one at a time does not work. Each change risks breaking an output you did not know was affected. The condition architecture needs to be redesigned as a whole, which in practice means rebuilding the condition and target framework from the ground up.
## Warning sign 2: Builds produce unexpected content
You build your output and find topics that should not be there. Or content that should be conditional appears in the wrong output. Or a PDF target includes sections that belong in the online help only.
Occasional build surprises happen in any project. But if your team has learned to treat every build as something that needs manual review before it can be trusted β if someone has to open every output and spot-check for content that leaked through β that is a structural problem, not an authoring error.
This usually traces back to one of two root causes: condition logic that has become too complex for anyone to reason about, or TOC structures that mix navigation and filtering in ways that produce unpredictable results. Both are architectural issues that do not respond well to incremental fixes.
## Warning sign 3: New writers take more than a month to become productive
Onboarding time is one of the most reliable indicators of project health. In a well-structured Flare project, a writer with basic Flare skills can start producing content within one to two weeks. They may not know every convention yet, but the project structure guides them. Folder names make sense. Templates exist. Naming conventions are consistent.
In a project heading for a rebuild, onboarding takes six weeks or more. New writers need a tour guide. They learn through oral tradition rather than self-evident structure. Senior writers maintain mental maps of where things are and how things work that are not encoded anywhere in the project itself.
The cost is not just the onboarding time. It is the ongoing dependency on institutional knowledge. When a senior writer leaves, the team loses part of its understanding of how the project works. That knowledge gap creates errors, slows everyone down, and reinforces the feeling that the project is fragile.
## Warning sign 4: You avoid changing shared content
Snippets, variables, and shared topics are the core of Flare's reuse model. In a healthy project, writers update shared content confidently because the impact is clear. The snippet is used in these five topics. The variable appears in these outputs. Change it, build, verify.
In a project heading for a rebuild, shared content has become untouchable. Writers duplicate snippets instead of editing them because they do not know what will break. Variables accumulate alternates β `ProductName`, `Product_Name`, `ProductNameNew` β because nobody wants to risk changing the original. Shared topics get forked into local copies because the sharing model has become unpredictable.
The paradox is clear: the reuse system exists, but nobody uses it as designed because the dependencies are invisible. This defeats the purpose of single-sourcing and causes content to drift out of sync across outputs.
## Warning sign 5: Build times have become a workflow bottleneck
Flare build times depend on project size, target complexity, and condition evaluation. A project with 1,000 topics and well-organized conditions might build in two to three minutes. The same topic count with tangled conditions, deeply nested snippets, and multiple preprocessing steps can take 15 to 30 minutes.
Long build times are not just an inconvenience. They change writer behavior. Writers stop previewing builds because the wait is too long. They batch their reviews instead of checking incrementally. Errors accumulate between checks. The feedback loop that keeps content quality high becomes too slow to be useful.
If your team has started working around build times β previewing individual topics instead of building targets, skipping builds during active authoring, or scheduling builds for overnight runs β the project structure is actively slowing down your workflow.
## The rebuild question
If you recognized your project in two or more of these warning signs, you are likely past the point where small fixes will make a meaningful difference. But a rebuild does not mean starting from a blank project. It means redesigning the architecture β conditions, file structure, reuse model, target configuration β and migrating content into that new structure.
Done well, a rebuild takes weeks, not months, and it pays for itself within the first quarter through reduced authoring time, faster onboarding, and reliable builds.
Done poorly β or avoided entirely β the cost compounds. Every month spent working around structural problems costs more than the month before because the workarounds themselves add complexity.
## Find out where you stand
The [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) is a free diagnostic tool that evaluates your project against common structural issues. It takes five minutes and gives you a clear picture of whether your project needs incremental improvement or structural intervention. If the results suggest a rebuild, [get in touch](/contact) to discuss the scope and approach.
---
## How to Enforce a Style Guide at Scale in MadCap Flare
Your style guide exists. Your writers know it exists. And yet every quarterly audit reveals the same inconsistencies β mixed terminology, heading structure violations, formatting drift. The problem is not awareness. It is that manual enforcement does not work at scale.
## Why manual enforcement fails
A typical technical writing style guide contains 50 to 200 rules covering terminology, structure, formatting, and tone. Some rules are simple: always use "click" instead of "click on." Others are contextual: use sentence case for headings in user guides but title case in API documentation.
A single reviewer checking a topic against all those rules needs 15 to 30 minutes per topic. For a team producing 20 to 50 topics per week, that is 5 to 25 hours of review time weekly β just for style compliance, not technical accuracy.
But the time cost is not the real problem. The real problem is inconsistency.
**Reviewers are human.** Reviewer A catches terminology issues but misses heading structure. Reviewer B focuses on formatting but overlooks tone violations. No single reviewer holds all 200 rules in active memory while reading. Each review is a sample, not a comprehensive check.
**Feedback is delayed.** Manual review happens after the topic is written, often days or weeks later. By then the writer has moved on. Context-switching back to fix style issues costs three to five times more than fixing them in the moment.
**Enforcement drifts.** Style guides evolve. New rules are added, old rules are clarified, edge cases are resolved. Reviewers update their mental model of the rules at different speeds. Six months after a style guide update, enforcement across your review team is uneven.
The result: your published documentation has a style compliance rate of roughly 70 to 80 percent on a good day. That remaining 20 to 30 percent creates a consistent background noise of inconsistency that erodes user trust and inflates translation costs.
## What automated enforcement looks like
Automated style enforcement encodes your rules into the authoring environment so violations surface while the writer is working β not during a review cycle days later.
Here is how this changes the workflow in MadCap Flare.
### Rules run in real time
When a writer opens a topic, the enforcement system evaluates the content against your configured rules. Violations appear immediately, marked in context with a description of the rule and a suggested fix. The writer sees "Use 'select' instead of 'choose'" while they are writing the sentence, not in a review comment two weeks later.
This immediate feedback loop is the single highest-impact change. Writers learn the rules faster because enforcement is continuous. New team members absorb the style guide through daily practice rather than reading a 50-page document and trying to remember it.
### Rules cover structure, not just text
Text-level rules β terminology, banned phrases, spelling variants β are the baseline. But the most valuable enforcement rules are structural.
- **Heading hierarchy.** Every topic must follow H1, then H2, then H3. No skipping levels.
- **Topic length.** Flag topics that exceed a configurable word count threshold, indicating they should be split.
- **List formatting.** Numbered lists for procedures, bulleted lists for non-sequential items.
- **Required elements.** Every procedure topic must have a "Prerequisites" section. Every API reference must include a "Parameters" table.
- **Naming conventions.** File names must follow a specific pattern. Snippet names must include their category prefix.
These structural rules are nearly impossible to enforce manually at scale. A reviewer would need to check every heading level, count words, verify list types, and confirm required sections β for every topic. Automated rules do this in milliseconds.
### Rules produce data
Manual review produces anecdotal feedback. Automated enforcement produces data. You can see exactly which rules are violated most frequently, which writers need additional guidance, and whether compliance rates are improving or declining over time.
This data transforms quality from a subjective judgment into a measurable metric. You can set targets: 95 percent compliance by end of quarter. You can identify training gaps: if 60 percent of terminology violations come from one product area, that team needs focused guidance. You can measure the ROI of your quality investment in concrete terms.
## Building your rule set
Starting with automated enforcement does not require encoding your entire style guide on day one. A phased approach works better and delivers faster results.
**Phase 1: Terminology.** Start with your 20 most important terminology rules. These are the terms that cause the most confusion, the most support tickets, or the most translation cost. Common examples: product names, UI element references, action verbs, and industry terms with specific preferred forms.
**Phase 2: Structure.** Add heading hierarchy rules, required section checks, and topic length limits. These rules catch the structural issues that manual review most often misses.
**Phase 3: Formatting and conventions.** Add rules for list formatting, note/warning block usage, cross-reference format, and file naming conventions. These are the rules that maintain consistency across large teams.
**Phase 4: Custom rules.** Add rules specific to your organization: regulatory compliance language, legal disclaimers, audience-specific phrasing, or domain-specific conventions.
Each phase takes one to two weeks to configure and roll out. Most teams see measurable improvement in consistency after Phase 1 alone.
## The downstream impact
Consistent style enforcement has effects beyond the documentation itself.
**Translation costs drop.** When terminology is consistent, translation memory match rates increase. Organizations localizing into multiple languages typically see 10 to 20 percent reduction in translation costs from source consistency alone.
**Support ticket volume decreases.** Consistent terminology means users find answers faster. When the documentation says "select" everywhere instead of alternating between "select," "choose," "pick," and "click," users can search effectively and trust the results.
**Onboarding accelerates.** New writers learn the style guide through enforced practice rather than memorization. The rules are embedded in the tool, not in a document that competes for attention with actual writing work.
**Review time shifts to value.** When mechanical style enforcement is automated, human reviewers focus on technical accuracy, clarity, and information architecture β the areas where human judgment is irreplaceable.
## Getting started in Flare
The [Mad Quality Plugin](/madquality-plugin) brings automated style enforcement directly into MadCap Flare's authoring environment. It supports terminology rules, structural checks, custom validation, and compliance reporting β all running inside Flare as you write. Take a look at how it works, and start with the rules that cost you the most to enforce manually.
---
## DITA to MadCap Flare: A Practical Conversion Guide
Moving from DITA to MadCap Flare is not a simple file conversion. It is an architecture change β from a topic-based XML standard with maps and specializations to a topic-based XML editor with its own structural model. Getting the files across is the easy part. Getting the architecture right is what determines whether the migration succeeds or creates a new set of problems.
## When the Move Makes Sense
Not every DITA environment should migrate to Flare. The decision depends on your team's situation, not on which tool is objectively better.
Migration makes sense when your team is spending more time fighting the DITA toolchain than writing content. If your build pipeline requires dedicated engineering support, if writers need command-line skills to publish, or if your DITA specializations have become maintenance burdens that only one person understands, Flare's integrated environment removes that operational overhead.
It also makes sense when your team size is small to mid-range. DITA excels in large, distributed authoring environments with dedicated information architects. Teams of two to ten writers often find that DITA's structural rigor costs more than it returns. Flare gives those teams structured authoring without requiring the infrastructure.
Migration does not make sense if you are actively using DITA specializations that encode domain-specific semantics, if you have a mature CCMS investment, or if your content is genuinely shared across multiple output pipelines beyond what Flare targets. In those cases, you are better off improving your DITA workflow than replacing it.
## What Changes Architecturally
The conceptual model shift matters more than the file format change. Here are the key architectural differences you need to plan for.
**Maps become TOCs.** DITA maps define the hierarchy and relationship between topics. In Flare, that role is filled by Tables of Contents. The mapping is conceptually similar but structurally different. DITA maps can include relationship tables, metadata cascading, and key definitions. Flare TOCs are simpler and more visual. You will need to decide where the relationship table logic goes β often it becomes explicit cross-references or relationship links in topics.
**Keys and keyrefs become variables and snippets.** DITA's key mechanism is powerful and abstract. A keyref can resolve to a topic, an image, a phrase, or a URI depending on the map context. Flare's equivalent is a combination of variables for text substitution and snippets for content reuse. The mapping is not one-to-one. Simple phrase-level keyrefs convert cleanly to Flare variables. Topic-level keyrefs become snippet references or direct topic links. URI keyrefs need manual handling.
**Conrefs become snippet references.** DITA content references pull content from one topic into another at an element level. Flare snippets serve the same purpose but work as standalone files rather than references into arbitrary elements. This means conref targets need to be extracted into dedicated snippet files during migration. If you have conrefs pointing into the middle of regular topics, those topics need restructuring.
**Conditional processing changes models.** DITA uses DITAVAL files to filter content based on attribute values. Flare uses condition tags applied to content elements, with conditions included or excluded per target. The logic is similar but the implementation is different. Your DITAVAL filtering rules translate into Flare condition tag sets and target configurations.
**Specializations have no equivalent.** If you have built custom DITA specializations β specialized topic types, domain-specific elements, or constrained models β there is no direct Flare equivalent. Specialized elements either map to standard Flare elements with custom classes, become snippet patterns, or require rethinking the content model.
## The Conversion Process
A practical DITA-to-Flare migration follows three phases: automated conversion, structural adaptation, and validation.
### Phase 1: Automated Conversion
Flare includes a DITA import wizard that handles the basic file conversion. It converts DITA topics to Flare XHTML topics, maps to TOCs, and handles standard elements. For straightforward DITA content β tasks, concepts, and references without specializations β the import wizard gets you 70 to 80 percent of the way.
What the wizard does well: heading structures, lists, tables, basic cross-references, image references, and standard DITA elements. What it does not handle well: conrefs into non-root elements, key-based content resolution, relationship tables, custom specializations, and metadata beyond title and description.
For everything the wizard misses, you need scripted conversion. XSLT transforms or Python scripts that process the DITA source and generate Flare-compatible output. The automation investment pays off immediately if you have more than 100 topics.
### Phase 2: Structural Adaptation
This is where the real work happens. After the files are converted, you need to rebuild the architecture in Flare's model.
Extract conref targets into snippet files. Reorganize the folder structure to match Flare conventions. Set up condition tags that replicate your DITAVAL filtering logic. Create variable sets from key definitions. Build TOC structures that capture the hierarchy and navigation your maps provided.
Do not try to replicate the DITA architecture inside Flare. Flare has its own structural idioms, and fighting them creates ongoing friction. Adapt the architecture to Flare's strengths instead of forcing Flare to behave like a DITA editor.
### Phase 3: Validation
After conversion and adaptation, validate everything. Build every target and check the output. Verify that conditional content resolves correctly. Confirm that snippet references work. Check cross-references. Compare output to your previous DITA-built output and flag differences.
This phase always takes longer than teams expect. Budget 20 to 30 percent of the total migration time for validation and cleanup.
## What to Automate
Manual migration is viable for small projects β under 50 topics. Beyond that, automation is not optional. Here is what to script.
**Conref extraction.** Write a script that identifies all conref targets, extracts them into standalone snippet files, and updates references. This is mechanical work that is error-prone when done by hand across hundreds of topics.
**Key resolution.** Map DITA keys to Flare variables or snippets and perform bulk replacement. A key map with 200 entries means 200 find-and-replace operations β scripting this takes an hour and eliminates days of manual work.
**Metadata migration.** Extract topic metadata from DITA prolog elements and apply it as Flare topic properties. Descriptions, authors, and keywords should carry over automatically.
**Style mapping.** Map DITA output classes to Flare stylesheet classes. If your DITA publishing used custom CSS, that mapping needs to be systematic, not ad hoc.
## Common Mistakes
**Trying to migrate everything at once.** Start with one deliverable β a single output that covers a manageable set of topics. Get it working end to end before expanding. Teams that try to migrate 2,000 topics in a single phase always underestimate the effort and lose momentum.
**Preserving DITA structure inside Flare.** If your Flare project still looks like a DITA project six months after migration, you have not actually migrated β you have relocated. Use Flare as Flare.
**Skipping the architecture review.** Converting files without reviewing the underlying content architecture means migrating structural problems from one tool to another. A migration is the best opportunity to fix information architecture issues. Take it.
## Next Steps
If you are evaluating a DITA-to-Flare migration and want to understand the scope before committing, [run the free Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) to assess your current documentation architecture. For hands-on migration support, [get in touch](/contact) β this is exactly the kind of project we specialize in.
---
## How to Use AI With MadCap Flare Without Destroying Your Content Structure
AI can cut your drafting time in half. It can also silently destroy the structural integrity of your Flare project in a single paste operation. The difference is not whether you use AI β it is how. Most technical writers are using AI in a way that creates more cleanup work than it saves.
## The Structure Leak Problem
Here is the workflow most Flare authors follow today. You select content from a Flare topic, paste it into ChatGPT or Claude, ask for a rewrite, copy the response, and paste it back into Flare. It looks efficient. The result reads better. And your content structure is now broken in ways you might not notice for weeks.
What happened during that round-trip? Your MadCap variables became plain text. Your snippet references vanished, replaced by the rendered content they contained. Your custom CSS classes reverted to default formatting. Your condition tags disappeared entirely. If the topic used drop-down text, togglers, or glossary term links, those are gone too.
This is what I call a structure leak. The content looks fine in the XML editor. It reads well in the output. But the structural elements that make your project maintainable β the variables, snippets, conditions, and class assignments β have been stripped out and replaced with hard-coded text.
The damage compounds silently. The next time someone updates the product name variable, this topic will not reflect the change. The next time someone edits the shared snippet, this topic still shows the old version. The next time someone builds a conditional output, this topic's conditions are missing and the content appears everywhere or nowhere.
## Why Copy-Paste Cannot Be Fixed
The problem is fundamental, not procedural. When you copy content from Flare and paste it into an AI chat interface, the structural markup is lost at the clipboard. AI tools work with plain text or basic Markdown. They have no concept of MadCap variables, snippet references, condition tags, or Flare-specific XHTML elements.
No amount of careful prompting fixes this. You can tell ChatGPT to "preserve the variables" β but the variables are not in the text you pasted. They were already gone before the AI saw your content. The information was lost at the boundary between Flare and the clipboard, not inside the AI.
You also cannot fix it by being more careful about what you paste back. Even if the AI's response is perfect, pasting it into Flare replaces structured XHTML with whatever the clipboard contains. Flare's XML editor does its best to interpret pasted content, but it cannot reconstruct structural elements that are not in the pasted data.
## The Structural Round-Trip Approach
The solution is to never let structural information leave the pipeline. Instead of copying raw content into an AI chat, you convert the Flare topic into a format that preserves structural markers, send that to the AI, and convert the response back into proper Flare XHTML.
In practice, this means representing Flare-specific elements as tokens that survive the AI round-trip.
Variables become token syntax like `{{ProductName.FullName}}` β text that AI recognizes as a placeholder and leaves intact. Snippet references become markers like `[snippet:warnings/electrical-hazard.flsnp]` that AI treats as embedded content blocks. Condition tags become annotations that the AI preserves even when rewriting surrounding text.
The AI does not need to understand what these tokens mean. It just needs to keep them in place while working on the content around them. Language models are good at this β they routinely preserve code blocks, URLs, and placeholder syntax when rewriting text.
After the AI returns its response, the tokens are converted back into proper Flare XHTML elements. Variables become `` tags. Snippet markers become `` references. Conditions are reapplied. The structural integrity survives the round-trip.
## What This Looks Like in Practice
With the [AI Helper Plugin](/ai-helper-plugin), the structural round-trip is built into the Flare workflow.
**Rewriting a topic.** Select the content, use Copy Topic as Markdown, paste into your AI tool, get the rewrite, and use Replace Topic to import the result. Variables, snippets, and classes come back intact. Total time: two minutes for a full topic rewrite with zero structural cleanup.
**Drafting new content.** Write your prompt, include variable tokens for product names and UI labels, generate the draft, and import it. The plugin converts Markdown headings to your configured Flare classes and creates proper variable references from the tokens. You get a structurally correct first draft instead of a formatting project.
**Batch operations.** Use Search and Compile to gather multiple related topics into a single Markdown document. Send the compiled content to AI for consistency analysis, terminology review, or bulk rewriting. Split the result back into individual topics. The structural elements in each topic survive the entire workflow.
**Working with llms.txt.** The plugin generates an [llms.txt](https://llmstxt.org/) index from your Flare project, making your documentation discoverable to AI tools in a standardized format. This means AI assistants can find and reference your content accurately instead of guessing from page titles and URLs.
## Rules for AI-Safe Flare Workflows
Whether you use a plugin or build your own workflow, these rules prevent structural damage.
**Never paste raw AI output into the XML editor.** Always convert through a pipeline that maps Markdown or plain text back to Flare XHTML with proper element references. Direct paste is where structure dies.
**Preserve variable tokens in prompts.** When sending content to AI, represent variables as tokens and instruct the AI to keep them in place. Most models handle this reliably when the tokens use a consistent syntax.
**Validate after every import.** Check that variables resolve, snippets render, and conditions apply correctly. A 30-second visual check after import catches problems before they propagate.
**Do not let AI generate Flare-specific markup.** AI should work with Markdown or plain text with tokens. The conversion to Flare XHTML should be handled by tooling that understands the Flare schema. Asking AI to write raw Flare XML produces markup that looks valid but misses namespace declarations, attribute requirements, or element nesting rules.
**Keep structural complexity in snippets.** If a content block has complex Flare markup β nested conditions, multiple variables, toggle sections β keep it in a snippet and reference the snippet from AI-written content. Let the snippet handle the structural complexity. Let AI handle the prose.
## The Productivity Math
Teams that adopt a structural round-trip workflow report consistent results. Drafting time drops by 40 to 60 percent. Structural cleanup time drops to near zero because structure is preserved automatically. The net productivity gain is 30 to 50 percent on content that involves rewriting, simplifying, or expanding existing topics.
The gain is smaller for purely original writing where there is no existing structure to preserve β roughly 20 to 30 percent. It is largest for maintenance tasks like updating content for a new product version, adapting content for a different audience, or standardizing terminology across a topic set.
The key number is not how fast AI writes. It is how much time you spend fixing what AI wrote before it is production-ready. A workflow that preserves structure makes that number close to zero.
## Getting Started
The lowest-risk way to start is with a single, non-critical topic. Export it to Markdown, send it to your preferred AI tool for a rewrite, and import the result back. Verify that the structural elements survived. Once you trust the round-trip, expand to routine workflows.
The [AI Helper Plugin](/ai-helper-plugin) handles the conversion, token management, and import for MadCap Flare. It includes a free 14-day trial β enough time to test the workflow on real content and measure the impact on your team's process.
---
## Before You Buy Another Documentation Tool: Run This Audit First
Documentation teams buy tools to solve problems. But most documentation problems are not tool problems β they are structural problems, process problems, or architecture problems that follow you from one tool to the next. Buying a new tool before diagnosing the actual bottleneck is the most expensive mistake in technical documentation.
## The Tool-Shopping Reflex
The pattern is predictable. Builds take too long. Writers cannot find content. Quality is inconsistent. Translation costs keep rising. The team meets, discusses the pain, and concludes: we need a better tool. Maybe a CCMS. Maybe a different authoring environment. Maybe an AI writing assistant. The budget gets approved. The migration happens. Six months later, the same problems persist in the new environment.
This happens because the symptoms pointed at the tool, but the root cause was somewhere else. Slow builds are usually caused by tangled conditions and unused content, not by the build engine. Writers cannot find content because the folder structure and naming conventions are unclear, not because the search function is inadequate. Quality is inconsistent because there is no automated enforcement, not because the editor lacks features.
A new tool cannot fix a broken content architecture. It can only give you a different interface to the same structural problems.
## What an Audit Actually Reveals
A proper documentation audit examines five dimensions that determine whether your documentation operation is healthy or accumulating hidden costs.
### Content Architecture
How is your content organized? Is there a clear, documented structure β or has the project grown organically for years without anyone stepping back to evaluate the architecture?
Concrete things to check: How many folders deep is your content hierarchy? Can a new writer find a topic in under 30 seconds? Are naming conventions documented and followed? Do your folder structures match your table of contents, or do they reflect an organizational chart from three years ago?
Projects with clean architecture scale smoothly. Projects with accumulated structural debt slow down with every hundred topics added. The tool is irrelevant if the architecture underneath is fighting you.
### Reuse Efficiency
Content reuse is the primary justification for structured authoring. But reuse implemented badly is worse than no reuse at all.
Measure your actual reuse rate. How many of your snippets or shared components are referenced more than once? In most projects I audit, 30 to 50 percent of snippets exist but are only used in a single location β they add complexity without reducing duplication. How many snippets reference other snippets? Nested reuse creates dependency chains that are nearly impossible to maintain and debug.
Also check for untracked duplication. How many places does the same content appear in slightly different forms, without using the reuse mechanism at all? If the same installation procedure exists in five topics with minor variations, you have a reuse problem that no tool purchase will fix.
### Conditional Logic
Conditions are the second most common source of documentation debt, after folder structure. They start simple β one condition for internal versus external, another for product variant A versus B. Then someone adds a condition for a specific customer. Then another for a temporary release note. Then a condition that interacts with two other conditions in ways nobody documents.
Audit your condition tags. How many exist? How many are actively used? Can any single person on the team explain what every condition does and how it interacts with the others? If the answers are "many," "we're not sure," and "no," then conditions are a bottleneck regardless of which tool you use.
The most telling test: can you confidently predict what a given target build will produce? If you have to build and check to find out, your conditional logic has exceeded human comprehension, and that is a process problem, not a tool problem.
### Quality Consistency
Open five random topics written by different authors. Do they follow the same structure? Do they use the same terminology for the same concepts? Are heading levels consistent? Do procedures follow the same format?
If the answer is no, you have a quality consistency problem. The fix is a combination of documented standards and automated enforcement. A style guide that nobody follows is not a style guide β it is a wish list. Automated quality gates that check every topic against defined rules turn the wish list into a reliable standard.
This is one area where tooling genuinely helps β but the tooling that helps is quality enforcement tooling, not a new authoring environment. You can add automated quality checks to your existing tool without migrating anything.
### Publishing and Delivery
How long does a build take? How many manual steps are required between "content is ready" and "content is published"? Are there manual formatting or post-processing steps that happen after the build?
Slow publishing is often the trigger for tool-shopping conversations. But slow builds are usually caused by project bloat β too many unused topics, too many conditions to evaluate, too many targets that nobody needs. Cleaning the project frequently cuts build times by 40 to 60 percent without changing any tooling.
Manual post-processing steps usually indicate that the authoring tool's output does not match what the delivery channel needs. The fix is configuring the output properly or writing a post-processing script, not replacing the tool.
## The Audit-First Decision Framework
After auditing these five dimensions, you land in one of three positions.
**The architecture is sound but the tool is genuinely limiting.** This is rare, but it happens. If your content is well-structured, your processes are clean, and the tool itself cannot produce the outputs you need or support the workflows you require, then a tool change is justified. Migrate with confidence β your architecture will transfer well.
**The architecture has problems that a tool change would not fix.** This is the most common finding. The right move is to fix the architecture in your current tool first. Clean up conditions, restructure folders, consolidate snippets, enforce quality standards. This is cheaper, faster, and less disruptive than a migration, and it actually solves the problem.
**Both the architecture and the tool need attention.** Fix the architecture first, then evaluate tools. A clean architecture makes tool evaluation meaningful because you can assess tools against clear requirements instead of hoping a new tool will somehow compensate for structural problems you have not diagnosed.
## Running the Audit
You can audit your own project. Block four hours, go through each dimension above, and document what you find. Be honest β the point is diagnosis, not justification for a decision you have already made.
If you want a structured framework, the [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) walks you through a systematic assessment of your MadCap Flare project across these dimensions and more. It is free, takes about 15 minutes, and produces a prioritized list of bottlenecks with specific recommendations.
For teams that want an external perspective or are dealing with large-scale architectural issues, [reach out directly](/contact). A professional audit typically takes one to two days and produces a concrete remediation plan with estimated effort and priority ranking for every issue found.
The point is simple: diagnose before you prescribe. The most expensive documentation tool is the one you bought to solve a problem it cannot fix.
---
## The Hidden Cost of a Bad Flare Migration β And How to Audit Yours
Most Flare migrations technically succeed. The content moves from the old system to the new one. Builds run. Outputs generate. Everyone declares victory. But six months later, writers are slower than before, builds take twice as long as they should, and nobody trusts the conditions. The migration didn't fail β it just deferred every structural decision to the future, and the future has arrived.
## What a "Successful" Migration Actually Produces
When teams migrate to MadCap Flare from FrameMaker, Word, DITA, or another CMS, the priority is always the same: get the content in, preserve the output, meet the deadline. That is a reasonable goal. The problem is what it leaves behind.
A typical rush migration produces a Flare project with these characteristics:
- **Flat folder structures** that mirror the source tool's organization, not the information architecture your users need
- **Auto-generated condition tags** that map to source-system metadata nobody fully understood in the first place
- **Heading hierarchies carried over from Word** where H3 follows H1 because the original author used font sizes instead of styles
- **Snippet boundaries drawn at paragraph level** because the conversion tool split content where it could, not where it should
- **Variable files containing hundreds of entries** imported in bulk with no grouping or naming convention
- **Cross-references converted to hardcoded links** that work today but break the moment someone renames a topic
None of these problems prevent output from generating. All of them make the project progressively harder to work in.
## How Structural Debt Compounds
The danger of migration debt is that it compounds silently. Each problem makes the next problem worse.
**Conditions become untouchable.** When condition tags are imported without a clear mapping strategy, writers stop trusting them. Instead of applying conditions correctly, they duplicate topics β one for Product A, one for Product B. Now you have two topics to maintain instead of one, and the condition system you migrated sits unused.
**Folder chaos slows every task.** When the folder structure doesn't match the TOC or the user's mental model, writers spend time searching for content instead of writing it. A writer who spends five minutes per topic locating the right file or snippet loses over an hour per day on a busy week. Multiply that across a team and across months.
**New writers absorb the debt.** Onboarding to a clean Flare project takes one to two weeks. Onboarding to a migrated project with undocumented conventions, mysterious conditions, and tangled snippets takes four to eight weeks. Every new hire inherits the full cost of decisions made during migration.
**Builds slow down invisibly.** Migrated projects often include content that no target actually uses β orphaned topics, unused snippets, conditions that evaluate to nothing. Flare still processes all of it. A project that should build in 30 seconds takes three minutes because it is dragging dead weight through every build cycle.
**Quality drifts downward.** When the project structure is unclear, writers make inconsistent choices. One writer nests snippets inside snippets. Another avoids snippets entirely and copies text inline. A third invents a new condition tag because they can't figure out the existing ones. Six months post-migration, the project has more structural problems than it did on day one.
## The Audit: Five Questions That Reveal Migration Debt
You don't need a week-long assessment to determine whether your migration left structural debt. These five questions surface the most common problems in under an hour.
**1. Can you explain every condition tag in your project?** Open your condition tag set. For each tag, state which target it affects, what content it includes or excludes, and why it exists. If you can't do this for more than half your tags, your condition architecture needs work.
**2. How many orphaned topics exist?** Run a build report and compare the topics included in your targets against the full topic list. The difference is your orphan count. Migrated projects routinely carry 15 to 30 percent orphaned content.
**3. Does your folder structure match your TOC?** Open your TOC and your Content Explorer side by side. If finding a TOC entry's source file requires searching because the folder doesn't match, your structure is costing you time on every edit.
**4. What is your snippet reuse rate?** Check how many snippets are referenced in more than one location. If most snippets are used exactly once, they are not enabling reuse β they are adding indirection with no benefit. This is common in migrations that mechanically converted shared content into snippets without evaluating whether the sharing pattern still made sense.
**5. How long does a clean build take versus an incremental one?** If a clean build takes significantly longer than the content volume justifies, the project likely includes processing overhead from migration artifacts β unused resources, deeply nested snippets, or conditions that force Flare to evaluate complex logic on every topic.
## What a Good Migration Architecture Looks Like
For comparison, a well-architected Flare project after migration has these properties:
- Folders mirror the TOC structure so that content location is predictable
- Condition tags are documented with a clear purpose-per-tag policy and organized by output type
- Variables are grouped into domain-specific files: product names, version strings, UI labels, company information
- Snippets exist only where genuine reuse occurs, with clear naming that indicates content and scope
- Cross-references use Flare's native linking, not hardcoded paths
- Heading hierarchy is enforced by topic templates, not by hoping writers follow convention
Getting from a migrated state to this state does not require rebuilding the project. It requires a structured audit followed by targeted refactoring β the kind of work that pays for itself within the first quarter through reduced authoring time and faster builds.
## Find Your Bottlenecks
If any of those five audit questions raised concerns, the next step is a structured diagnosis. The [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) is a free tool that walks you through the most common structural problems and maps them to specific, actionable fixes. It covers conditions, folder structure, snippet architecture, build performance, and more.
For projects with deep migration debt β where conditions are entangled, snippet chains are three levels deep, or nobody is sure what a build actually includes β [get in touch directly](/contact). Untangling migration architecture is a significant part of what we do as a MadCap Flare consultant, and the pattern is consistent enough that the path from diagnosis to resolution is well-established.
And if the migration ahead of you starts from Word, work from the free [47-step Word to MadCap Flare migration checklist](/guides/word-to-flare-migration-checklist) β most of the cost described in this post comes from skipping its first 24 steps.
---
## Quality Drift in Documentation: How It Starts, How It Compounds, How to Stop It
Nobody ships a documentation project with the intention of letting quality degrade. It happens anyway. Not in a single event, but through hundreds of small decisions β a shortcut here, an exception there, a new writer who follows the patterns they see instead of the patterns you intended. This is quality drift, and by the time it becomes visible, the cost of fixing it has multiplied.
## How Quality Drift Starts
Quality drift rarely begins with negligence. It begins with reasonable decisions made under normal pressure.
**A writer copies formatting from an existing topic.** The existing topic was written before the current style guide. The new topic now inherits the old conventions. If no one catches it in review, the old pattern gets reinforced.
**A condition tag gets repurposed.** The original tag was created for a specific output. A new requirement comes in and someone applies the same tag to a different scenario because creating a new one feels like overhead. Six months later, nobody can explain what the tag actually controls.
**A snippet gets edited for one context.** The snippet was shared across five topics. The edit makes it perfect for one and slightly wrong for the other four. Nobody notices until a customer reports contradictory instructions across two help pages.
**A heading level gets skipped.** A writer goes from H1 directly to H3 because the visual result looks right in their browser. The HTML structure is wrong, but the output passes a visual check. Screen readers, search engines, and AI parsers all misinterpret the content hierarchy.
**Terminology shifts without announcement.** Marketing renames a feature. One writer updates their topics. Another doesn't. A third uses both the old and new name in the same topic, hedging. The documentation now contains three naming conventions for one feature.
Each of these is minor in isolation. Combined across a team over 12 months, they transform a clean project into one where no single source of truth exists for how content should look, read, or behave.
## The Compounding Effect
Quality drift doesn't stay small. It compounds because each deviation becomes a reference point for future work.
**New writers learn from existing content.** When a new team member joins, they learn conventions by reading what's already published. If 30 percent of topics use inconsistent heading styles, the new writer has a 30 percent chance of learning the wrong convention on any given day. After a month, they are producing content that matches the project's actual state rather than its intended state.
**Reviews catch less over time.** Reviewers calibrate their expectations to what they see. When drift has accumulated for months, the reviewer's internal standard shifts to match. Violations that would have been flagged in month one pass without comment in month six.
**Automated processes amplify inconsistency.** Translation memory, search indexing, and AI tools all work better with consistent input. Inconsistent terminology inflates translation costs. Inconsistent structure degrades search rankings. The downstream systems do not compensate for drift β they faithfully propagate it.
**Cleanup becomes a project, not a task.** When drift is caught early, correction takes minutes. When it has spread across hundreds of topics over several release cycles, correction requires a dedicated remediation effort. Teams that delay don't save time β they convert small ongoing maintenance into large periodic projects that disrupt roadmaps.
## Measuring Drift
You cannot manage what you don't measure. Most teams have no visibility into quality drift because they lack baseline metrics.
Here is a practical way to measure it.
**Select 20 topics at random from your project.** Not the ones you just published. Not the showcase topics. Random selection across different authors and publication dates.
**Check each topic against your five most important style rules.** These might include heading hierarchy, approved terminology, sentence structure requirements, or formatting conventions. Score each topic as compliant or non-compliant for each rule.
**Calculate your compliance rate.** If your five rules across 20 topics give you 100 checkpoints and 70 pass, your compliance rate is 70 percent. That means roughly one in three rule applications deviates from the standard.
**Repeat quarterly.** The trend matters more than the absolute number. A rate that drops from 85 to 70 percent over two quarters tells you drift is active and accelerating.
Most teams that run this exercise for the first time are surprised. The perceived quality is almost always higher than the measured one because humans compensate for inconsistency when reading. Machines don't.
## Stopping Drift: The Three-Layer Approach
Reversing quality drift requires action at three levels. Any single layer helps, but sustainable quality requires all three.
### Layer 1: Define the Standard
You cannot enforce what you haven't documented. If your style guide is a 40-page PDF that nobody has opened since onboarding, it is not functioning as a standard. Reduce it to the 20 rules that matter most. Write each rule as a concrete instruction, not a principle. "Use sentence case for all headings" is enforceable. "Headings should be clear and consistent" is not.
### Layer 2: Automate Enforcement
Manual review cannot prevent drift at scale. The rules that can be expressed as patterns β heading hierarchy, approved terminology, formatting conventions, prohibited constructions β should be enforced automatically, inside the authoring tool, at the moment of writing.
This is what the [Mad Quality Plugin](/madquality-plugin) does for MadCap Flare projects. It encodes your style rules into automated checks that run while writers work. Violations surface immediately, not during review two weeks later. The tool doesn't forget rules, get fatigued, or reinterpret guidelines.
### Layer 3: Measure and Correct
Automation catches new violations. Measurement catches accumulated drift in existing content. Combine both: use automated enforcement for new and edited topics, and run periodic compliance audits on the full project. Sort non-compliant topics by traffic or business impact, fix the highest-impact topics first, and treat remediation as a standing backlog item.
## The Cost of Waiting
Teams sometimes acknowledge drift but defer action because the current state is "functional." This is a rational short-term assessment and a costly long-term one. Every quarter you defer, the remediation scope grows β more topics affected, more bad patterns absorbed by new writers, higher translation costs. The teams that address drift early, when compliance is at 80 percent instead of 60, spend a fraction of the effort. The teams that wait until a customer complaint or a failed audit exposes the problem pay for both the remediation and the consequences of the delay.
## Start With Diagnosis
If you suspect quality drift in your Flare project but aren't sure where to focus first, the [Flare Bottleneck Diagnosis](/flare-bottleneck-diagnosis) will help you identify the structural issues that contribute most to drift. It covers conditions, naming conventions, snippet architecture, and content consistency.
For teams ready to move from diagnosis to enforcement, the [Mad Quality Plugin](/madquality-plugin) brings automated style checking directly into the MadCap Flare authoring workflow β closing the gap between your documented standards and what actually ships.
---
## Making Your Documentation AI-Ready with llms.txt
AI tools are changing how people find and consume documentation. But most documentation systems weren't built for AI consumption β they were built for browsers. The result: AI models struggle to extract structured knowledge from your help output, and your users get incomplete or hallucinated answers.
The **llms.txt** standard changes that.
## What is llms.txt?
[llms.txt](https://llmstxt.org/) is a proposed standard that provides a structured index of your documentation in a format optimized for large language models. Think of it as `robots.txt` for AI β instead of telling crawlers what *not* to index, it tells AI models exactly *what* to read and how your content is organized.
A typical `llms.txt` file looks like this:
```
# Project Name
> Brief description of the project
## Section Name
- [Topic Title](https://example.com/docs/topic.md): Short description
- [Another Topic](https://example.com/docs/another.md): Short description
```
## Why it matters for technical documentation
Traditional help output β HTML with navigation chrome, JavaScript widgets, and complex layouts β is noisy for AI. Models waste context window on sidebars, footers, and UI elements instead of your actual content.
With llms.txt and companion Markdown files, you give AI models:
1. **A clean table of contents** β the structure of your documentation in a machine-readable format
2. **Pure content** β Markdown files stripped of layout noise, with just the information that matters
3. **Metadata** β descriptions that help models understand what each topic covers before loading it
## How to generate llms.txt from MadCap Flare
The [AI Helper Plugin](/ai-helper-plugin) includes a dedicated LLMS.txt Tools tab that generates these files directly from your Flare build output:
- **Generate LLMS.txt** β Converts your HTML build output into clean Markdown files and creates a structured `llms.txt` index following your TOC hierarchy
- **Generate Markdown Target** β Creates a standalone documentation package with only essential files (Markdown, images, resources), ready for AI consumption
- **Add Description** β Lets you add or edit description meta tags per topic, which are automatically extracted during generation
The process is straightforward: build your Flare project as usual, then run the LLMS.txt generator. It parses your TOC structure, converts HTML to clean Markdown, and produces a properly formatted `llms.txt` that maps your entire documentation.
## Configuration options
The plugin gives you control over how the output is generated:
- **Auto-append .md to filenames** β Choose between `file.htm.md` or `file.md` format
- **Glossary Term Handling** β Control how MadCap glossary popups are processed: remove definitions, keep inline, or append as a glossary section
## What this means for your users
When your documentation has an `llms.txt`, AI-powered tools can:
- **Answer questions accurately** by reading the actual source documentation instead of guessing
- **Reference specific topics** with proper links back to your help system
- **Understand context** β the hierarchy tells the AI how concepts relate to each other
- **Stay current** β regenerate after each build, and AI tools always have the latest version
## Getting started
1. Install the [AI Helper Plugin](/ai-helper-plugin) in MadCap Flare
2. Build your project normally
3. Open the LLMS.txt Tools tab
4. Click **Generate LLMS.txt** and point it to your build output
5. Deploy the generated files alongside your documentation
The AI-readiness of your documentation goes from zero to complete in a single build step.
---
## RAG Pipelines and Documentation: Why the Content Layer Is Your Biggest Risk
Your RAG pipeline is only as good as the content it retrieves. Teams spend months tuning embeddings, chunking strategies, and prompt templates β then feed the system documentation that was never designed for machine consumption. The result is confident, well-formatted answers built on garbage retrieval. The content layer is where most RAG implementations silently fail.
## How RAG Actually Works (and Where It Breaks)
A Retrieval-Augmented Generation pipeline follows a deceptively simple pattern. A user asks a question. The system converts that question into a vector embedding, searches a document store for semantically similar chunks, retrieves the top results, and feeds them to a language model as context for generating an answer.
Every step in that chain depends on the quality of what was indexed. If the source documentation is structurally inconsistent, terminologically ambiguous, or cluttered with navigation artifacts, the pipeline degrades at every stage β embedding, retrieval, and generation.
The failure mode is subtle. The system still produces answers. They still sound authoritative. But they are assembled from poorly matched chunks, missing context, or contradictory fragments. Your users cannot tell the difference until the answer sends them down the wrong path.
## The Five Documentation Problems That Degrade RAG Output
After working with teams building RAG systems on top of technical documentation, the same structural problems appear repeatedly.
**Inconsistent terminology creates retrieval collisions.** When your documentation calls the same feature "Dashboard," "Control Panel," and "Home Screen" across different topics, the embedding space gets polluted. A user query about the dashboard may retrieve chunks about the control panel with high similarity scores β but those chunks describe a slightly different workflow in a different context. The model stitches them together and produces an answer that is technically plausible but functionally wrong.
**Missing or generic metadata breaks chunk boundaries.** RAG systems chunk documents before indexing. Without clear structural markers β proper headings, topic boundaries, and metadata β the chunker splits content at arbitrary points. A procedure that spans two chunks loses its logical sequence. A concept explanation gets severed from its prerequisite. The retrieved chunks are fragments, not complete thoughts.
**Navigation chrome pollutes the index.** HTML help output includes breadcrumbs, sidebars, footer links, related topic lists, and cookie consent text. If you index this output directly, your vector store contains thousands of near-identical navigation chunks. These compete with actual content for retrieval slots, pushing relevant documentation out of the top results.
**Unresolved conditional content creates contradictions.** Documentation tools like MadCap Flare support conditional tags that show different content for different audiences or products. If conditions are not resolved before indexing, the RAG system ingests multiple conflicting versions of the same procedure. The model has no way to know which version applies and may combine elements from both.
**No structural index means no retrieval hierarchy.** Without a machine-readable map of how topics relate to each other, the RAG system treats every chunk as an independent fragment. It cannot distinguish a high-level overview from a detailed procedure, or understand that Topic A is a prerequisite for Topic B. Retrieval becomes flat β every chunk competes equally regardless of its role in the information architecture.
## What Good RAG Source Content Looks Like
Documentation that performs well in RAG pipelines shares specific structural properties. These are not subjective quality preferences β they are engineering requirements.
**One concept per topic.** Topics that cover a single, well-scoped concept produce chunks that are self-contained and semantically coherent. When a retrieval system pulls a chunk from a focused topic, the chunk carries enough context to be useful on its own.
**Consistent, controlled terminology.** When the same term always means the same thing, embedding similarity maps to actual semantic similarity. Retrieval precision goes up. Contradictory chunks go down. This is the single highest-leverage fix for most RAG implementations.
**Clean content with no presentation artifacts.** The indexed content is pure information β no navigation elements, no JavaScript-dependent widgets, no layout markup. What gets indexed is what the model should read, and nothing more.
**Proper heading hierarchy and metadata.** Clear structural markers give chunking algorithms natural split points. Title and description metadata provide the retrieval system with topic-level context that helps rank results. A well-structured topic produces well-structured chunks.
**A machine-readable content map.** A structured index like [llms.txt](/blog/making-documentation-ai-ready-with-llmstxt) tells the RAG system what exists, where it lives, and how topics relate. This enables smarter retrieval strategies β the system can first identify relevant topic areas, then retrieve specific chunks within those areas.
## The Practical Fix: Work Backward from the Pipeline
Most teams try to fix RAG quality by tuning the pipeline. They adjust chunk sizes, experiment with different embedding models, add re-ranking layers, and engineer more elaborate prompts. These are all legitimate optimizations. They are also optimizations applied to the wrong layer.
Start with the content.
**Step 1: Audit your source output.** Convert a representative sample of your documentation to Markdown. If the Markdown is messy β if it contains navigation debris, broken formatting, or ambiguous structure β that is exactly what your RAG pipeline is working with. Every artifact you see is a retrieval problem waiting to happen.
**Step 2: Fix terminology first.** Identify the 20 terms most critical to your product. Verify they are used identically across every topic. Automated enforcement is the only way to make this sustainable. The [Mad Quality Plugin](/madquality-plugin) can encode your terminology rules directly into the authoring workflow so inconsistencies stop at the source.
**Step 3: Generate a clean AI-consumable output.** Your RAG pipeline should not index your browser-facing HTML. It should index clean Markdown or structured text with metadata intact and navigation stripped. The [AI Helper Plugin](/ai-helper-plugin) generates this output from MadCap Flare projects, including an llms.txt index that provides the structural map your retrieval system needs.
**Step 4: Resolve conditions before indexing.** Build separate outputs for each audience or product variant. Index each one independently. Never index unresolved conditional content.
**Step 5: Measure retrieval quality, not just generation quality.** When users report bad answers, trace the problem back to what was retrieved. In most cases, the model did exactly what it was asked β it generated a coherent answer from the chunks it received. The problem was which chunks it received.
## This Is an Architecture Problem, Not an AI Problem
Teams that treat RAG output quality as a model problem will keep chasing diminishing returns on pipeline tuning. Teams that treat it as a content architecture problem will fix the root cause.
The documentation your organization already maintains is probably the single largest source of structured knowledge about your product. Making it work for RAG is not a separate initiative β it is the same structural investment that improves search, translation, content reuse, and human readability.
If your RAG pipeline is producing inconsistent results and you have not audited the content layer, start there. Run the [free bottleneck diagnosis](/flare-bottleneck-diagnosis) to identify structural issues in your Flare project, or [get in touch](/contact) to discuss how to make your documentation a reliable foundation for AI-powered retrieval.
---
## Migration as Architecture Upgrade: The Strategy Behind a Good MadCap Flare Conversion
> **Looking for the service page?** This post is the thinking behind the approach. For scope, transform rules, and pricing, see [MadCap Flare conversion](/madcap-flare-conversion/) β or [MadCap Flare migration services](/madcap-flare-migration/) for the full project view.
A MadCap Flare conversion is usually treated as a logistics problem β move content from the old tool to the new one, preserve formatting, hit the deadline. That approach guarantees you will carry every structural problem from the old system into the new one. The migration is your best opportunity to fix what was always broken. Here is how to use it.
## Why Migrations Are Architecture Opportunities
Every documentation system accumulates structural debt. Inconsistent heading levels. Terminology that drifted across authors and years. Topics that were designed for a product version three releases ago. Formatting workarounds that made sense in the old tool but have no equivalent in the new one.
In normal operations, fixing this debt is nearly impossible to justify. The content works. Users can find answers. The cost of a systematic cleanup competes with every other priority on the backlog, and it loses every time.
A migration changes the calculus. You are already touching every topic. You are already rebuilding templates and stylesheets. You are already revalidating output. The marginal cost of fixing structural issues during migration is a fraction of what it would cost as a standalone project. The question is not whether you can afford to fix the architecture during migration. It is whether you can afford not to.
## The Lift-and-Shift Trap
The most common migration approach is lift-and-shift: convert content from the old format to MadCap Flare format with maximum fidelity. Every heading, every inline style, every table preserved exactly as it was. This feels safe. Stakeholders see familiar output and sign off quickly.
But lift-and-shift imports the old system's limitations as the new system's baseline. Problems baked into the source β inconsistent styles, hard-coded formatting, missing metadata, duplicated content β arrive in Flare fully intact. Worse, they now look intentional because they survived the migration process.
Six months later, writers are working around the same problems in a new tool. The migration delivered a format change, not an improvement. The architecture debt remains, and now it is harder to address because "we just migrated and everything was reviewed."
## What an Architecture-First Migration Looks Like
An architecture-first MadCap Flare conversion treats the migration as a design project, not a copy operation. Before any content moves, you define what the target architecture should be. Then you use the migration process to close the gap between current state and target state.
Here is the sequence that works.
### 1. Audit Before You Convert
Before converting a single file, analyze the source content for structural patterns and problems. You are looking for:
- **Heading level usage.** Are headings used consistently, or do some authors skip levels? Are headings used for visual formatting rather than structure?
- **Style usage.** How many distinct styles exist? How many are actually needed? Which ones are author-created workarounds for limitations in the old tool?
- **Topic granularity.** Are topics focused on a single concept, or do mega-topics cover everything about a feature in one long page?
- **Content duplication.** Are the same procedures repeated across multiple topics? Is the same warning or note copy-pasted rather than reused?
- **Terminology.** Does the documentation use consistent terms for the same concepts, or has terminology drifted across authors and releases?
This audit gives you the scope for the architecture work β you know exactly what needs to change and can estimate the effort accurately.
### 2. Define the Target Architecture
Based on the audit, define the structural standards the migrated content should meet. This is a specification, not a wish list.
- **Topic model.** One concept, one task, or one reference item per topic. Set the boundary and apply it uniformly.
- **Heading hierarchy.** H1 for the topic title, H2 for major sections, H3 for subsections. No skipping. No headings for visual emphasis.
- **Style inventory.** Map old styles to new ones. Identify styles to eliminate. In MadCap Flare, set up your stylesheet before migration, not after.
- **Reuse strategy.** Identify content that should become snippets, variables, or conditions. Set up reuse components in Flare before importing content.
- **Metadata requirements.** Define what every topic must have β title, description, keywords, audience tags. Build the topic template with these fields from the start.
### 3. Convert With Transformation Rules
With the target architecture defined, set up the conversion to apply transformation rules rather than performing a straight format translation.
- Map old styles to new styles based on your style inventory, not one-to-one
- Split mega-topics into focused topics during conversion
- Strip inline formatting that should be handled by stylesheets
- Flag content that needs manual review for terminology, accuracy, or restructuring
- Apply metadata templates so every imported topic has the required fields, even if they need to be filled in manually
This is where the migration becomes an architecture upgrade. The conversion itself does part of the work. The rest is targeted manual effort on flagged items, which is far more efficient than reviewing every topic from scratch.
Here is a short demo showing what this looks like in practice β taking a messy imported topic and cleaning it up during migration:
### 4. Enforce Standards From Day One
The migrated content now meets your target architecture. The next problem is keeping it there. Without enforcement, standards drift back toward inconsistency within months.
Set up automated quality gates before the first writer opens the migrated project. Encode your heading conventions, terminology rules, and style restrictions into tools that check compliance in real time. The [Mad Quality Plugin](/madquality-plugin) does this directly inside MadCap Flare β writers see violations while authoring, not weeks later during review. This is the step most migration projects skip, and it is the step that determines whether the architecture upgrade survives contact with daily production.
## What You Gain
A well-executed architecture-first MadCap Flare conversion delivers compound returns. Maintenance costs drop because clean, consistent content is faster to update β writers spend time on substance, not on deciphering inherited formatting. Content reuse through snippets and conditions actually works when topics are properly scoped and styles are consistent. The documentation is AI-ready from day one, with the structured terminology and clean metadata that AI tools require. And scaling β adding writers, topics, languages, or output formats β becomes straightforward instead of exposing structural debt at every turn.
You will never have a better opportunity to fix your documentation architecture than during a migration. The content is already in motion. The budget is already allocated. The team is already prepared for change. Use that window to build the foundation right, not to replicate what you had before in a new format.
If you are planning a [MadCap Flare conversion](/madcap-flare-conversion/) and want to assess the structural opportunities in your current content, run the [free bottleneck diagnosis](/flare-bottleneck-diagnosis). For the full project view including audit, target-architecture design, transform rules, validation, and handover, see [MadCap Flare migration services](/madcap-flare-migration/). Or, if you already know the source format you're moving from, jump straight to the source-specific guide: [FrameMaker to Flare](/madcap-flare-migration/framemaker/), [RoboHelp to Flare](/madcap-flare-migration/robohelp/), or [Word to Flare](/madcap-flare-migration/word/). Word migrations also have a free companion resource: the [47-step Word to Flare migration checklist](/guides/word-to-flare-migration-checklist).
---
## What "AI-Ready Documentation" Actually Means β And How to Get There
Everyone says documentation should be "AI-ready." Few can explain what that means in practice. It is not a marketing label. It is a set of measurable structural properties that determine whether AI tools can use your content or will hallucinate around it.
## A Practical Definition
AI-ready documentation is content that a large language model can ingest, interpret correctly, and use to generate accurate answers β without human intervention to clean, restructure, or reformat it first.
That breaks down into four concrete requirements.
**Machine-readable structure.** The content has a clear hierarchy that software can parse. Headings follow a logical nesting order. Lists are actual lists, not paragraphs with dashes. Tables are real tables. Metadata like titles, descriptions, and categories exist and are accurate.
**Clean content separation.** The information is separated from its presentation. Navigation chrome, JavaScript widgets, cookie banners, and layout elements are not mixed into the content that AI needs to read. When an AI model loads a page, it gets the content, not the wrapper.
**Consistent terminology.** The same concept uses the same term everywhere. If your product has a "Dashboard" in one topic and a "Control Panel" in another and a "Home Screen" in a third, an AI model has no reliable way to know these are the same thing. Terminology consistency is not just a style preference β it is a structural requirement for AI comprehension.
**Discoverable organization.** The AI can find what it needs without crawling your entire site. A structured index, table of contents, or standard like [llms.txt](/blog/making-documentation-ai-ready-with-llmstxt) tells the model what exists, where it lives, and how topics relate to each other.
## The Audit Checklist
Here is how to evaluate whether your documentation is AI-ready today. Score each item as pass, partial, or fail.
### Structure
- Heading levels follow a strict hierarchy (H1, then H2, then H3 β no skipping)
- Topics have accurate title and description metadata
- Lists and tables use proper semantic markup, not visual formatting tricks
- Code examples are in actual code blocks with language annotations
### Content Cleanliness
- Exporting or converting a topic to Markdown produces clean, readable output
- No JavaScript-dependent content that disappears in a static render
- Glossary terms and popups resolve to inline text or a reference section
- Conditional content is resolved for each output, not left as raw tags
### Terminology
- A controlled vocabulary or style guide defines canonical terms
- Synonyms and variations are documented and enforced
- Product names, feature names, and UI labels are used consistently across all topics
- Abbreviations are defined on first use or in a glossary
### Discoverability
- A table of contents or sitemap covers all published topics
- Topic descriptions summarize what each page covers (not just the title)
- Related topics are linked, giving AI context for how concepts connect
- An llms.txt file or equivalent machine-readable index exists
If you scored mostly "fail" or "partial" on these items, AI tools interacting with your documentation are working with degraded input. The answers they produce will reflect that.
## Common Failure Points
After working with documentation teams across industries, the same problems appear repeatedly.
**HTML output treated as the final format.** Teams build to HTML and consider the job done. But HTML help output is designed for browsers, not AI. It contains navigation frames, search widgets, breadcrumbs, and layout markup that pollute the actual content. AI models either waste context on this noise or misinterpret it as content.
**Metadata is missing or generic.** Many topics have no description meta tag, or the description is auto-generated from the first 160 characters, which is often a partial sentence that means nothing out of context. AI relies heavily on metadata to understand what a topic covers before deciding whether to load it. Missing metadata means missed content.
**Inconsistent structure across authors.** Writer A uses H2 for major sections. Writer B uses H3. Writer C uses bold text instead of headings. When structure is inconsistent, AI cannot reliably parse the content hierarchy. What looks fine in a browser becomes ambiguous to a parser.
**No machine-readable index.** Documentation exists as a collection of pages with no structured map. The AI has to guess which pages are relevant based on URLs and page titles alone. Without a proper index, models either load too many pages and hit context limits, or miss critical content entirely.
**Glossary and conditional content left unresolved.** MadCap Flare and similar tools support glossary popups, drop-down text, and conditional tags. These are powerful authoring features. They are also invisible to AI unless they are resolved during output. A glossary term that only appears on hover is a glossary term that AI never sees.
## How to Get There
The gap between current state and AI-ready is usually smaller than teams expect. It is not a rewrite. It is a set of targeted structural improvements.
**Start with the index.** Generate an llms.txt file from your existing output. This single step makes your documentation discoverable to AI tools immediately. The [AI Helper Plugin](/ai-helper-plugin) does this directly from MadCap Flare build output.
**Add or fix metadata.** Write a real description for every topic. One or two sentences that summarize what the page covers. This is also good for search engine results, so the effort serves double duty.
**Run a structure audit.** Check heading hierarchy, list markup, and table structure across a representative sample. Fix systematic issues first β if every writer skips H2 and goes straight to H3, that is a one-time correction with outsized impact.
**Enforce terminology.** Identify your 20 most important terms and verify they are used consistently. Automated enforcement tools make this sustainable at scale rather than a one-time cleanup that drifts back.
**Generate clean Markdown output.** Convert your HTML output to Markdown and review the result. If the Markdown is messy, so is what AI sees. Use the conversion as a diagnostic β every formatting artifact in the Markdown is a problem AI will encounter.
## The Payoff
AI-ready documentation is not just about AI. Every improvement on this list β better structure, cleaner content, consistent terminology, proper metadata β also improves search results, translation quality, content reuse, and human readability.
The difference is that these problems were always there. AI just makes them visible because models fail loudly where humans compensate silently.
The teams that invest in structural quality now will have documentation that works across every channel β browsers, search engines, AI assistants, and whatever comes next. The teams that do not will keep patching symptoms while the underlying problems compound.
If you work in MadCap Flare, the [AI Helper Plugin](/ai-helper-plugin) handles the conversion, Markdown generation, and llms.txt creation in a single workflow. For teams that need help with the broader structural audit, [get in touch](/contact) β documentation architecture is what we do.
---
## Customer Survey Results: NPS 94 and Real Productivity Gains for Technical Writers
We recently asked Improvementsoft users a simple question:
**"How likely are you to recommend Improvementsoft to a peer?"**
The result: **Net Promoter Score: 94**
For context, an NPS above 70 is considered world-class. A score of 94 means that nearly every customer who responded would actively recommend Improvementsoft tools to their peers.
But numbers are only part of the story. The most interesting part of the survey was how customers described the impact on their work.
## What Customers Are Saying
> *"Backed by one of the most responsive and customer-centric vendors I've worked with in over a decade, Kaizen Plugin has been mission-critical to my documentation work for over five years."*
> β Lesley R., Content Architect & Technical Writer
> *"The plugins help our team complete tasks faster than before, and when we have a question or suggestion they respond quickly. The agility of Improvementsoft has made our work life so much easier."*
> β Deb McNally, Amadeus
> *"The Kaizen Plugin was essential to my Flare workflow and the productivity features alone saved me countless hours."*
> β Shay Adler
> *"Your tools have saved me and my team many hours of work by reducing the time spent creating bulk topics and maintaining the quality of our projects."*
> β Andrew Bridle
> *"The Kaizen Toolbar has saved me oodles of hours by automating tasks. As a consultant, time is money, and the toolbar frees up time for better design and structure in the completed projects."*
> β Jack DeLand
> *"Using Kaizen to import topics, snippets, and other files from Excel has enabled us to continue using Excel to maintain structured content and update Flare quickly and without error."*
> β Matthew Ellison
> *"Very positive experience with Improvementsoft. Kaizen is a very useful plugin for MadCap Flare, constantly kept up-to-date and issues are addressed quickly."*
> β Kees de Jong
> *"Excellent software, excellent service."*
> β Anonymous user
## What Customers Achieved
Across the feedback, a few themes appeared again and again.
### Major Time Savings
Customers repeatedly described saving hours of work by automating repetitive tasks such as:
- Splitting large topics automatically
- Bulk topic creation from Excel
- Generating PDF, Word, and HTML outputs quickly
- Replacing styles across entire projects
- Validating XML and catching issues before builds
One customer described the XML validation feature as:
> *"A godsend far too many times."*
### Higher Documentation Quality
Teams also highlighted how Improvementsoft tools help enforce structure and standards.
> *"Mad Quality significantly improved quality. Writers no longer have to look up the gazillion writing rules β the plugin checks their content for them."*
> β Anonymous documentation team lead
### Faster Publishing Workflows
Many users pointed to Kaizen's productivity tools and the AI Helper plugin as removing friction from daily workflows.
> *"The AI Helper quite literally enabled me to meet major release deadlines during extreme staffing shortages."*
> β Lesley R., Content Architect & Technical Writer
## Long-Term Usage
Another strong signal from the survey: many customers described using Improvementsoft tools daily and in some cases for more than five years.
Tools that stay in a workflow that long usually have one thing in common: they quietly remove a lot of friction.
## Thank You
To everyone who shared feedback and experiences: thank you.
Improvementsoft exists to help technical writers spend less time fighting tools and more time creating great documentation.
Based on this feedback, we're heading in the right direction.
Explore the tools mentioned in this post: [Kaizen Plugin](/kaizen-plugin), [Mad Quality Plugin](/madquality-plugin), and [AI Helper Plugin](/ai-helper-plugin).
---
## What Does a Documentation Topic Actually Cost to Produce?
Most documentation teams can answer how many topics they produce. Very few can answer what each topic costs.
Not the team salary. Not the tool license. The actual cost of producing one usable documentation topic β from first draft to published output.
## Documentation Is a Production System
Factories measure cost per unit. Software teams measure cost per feature. But documentation teams rarely measure cost per topic.
Yet documentation follows the same economics as any production system. Each unit moves through a workflow with identifiable inputs: writing effort, engineering input, review cycles, waiting time, and overhead. Each of those inputs has a cost. And when you add them up per topic, the number is usually higher than anyone expected.
## The Cost Drivers That Nobody Tracks
Most managers assume that writing time is the dominant cost. In the teams I have worked with, it rarely is. The real drivers are often invisible because nobody measures them.
**Waiting time.** Writers wait for engineers to answer questions. They wait for reviewers to respond. They wait for product decisions. This idle time acts like downtime in a factory β the production line stops, but the costs continue. In many organizations, waiting accounts for more than a third of the total time a topic spends in production.
**Engineering support.** Every topic that requires a subject matter expert consumes engineering capacity. An engineer spending one hour per topic explaining a feature or reviewing a draft may seem reasonable. Multiply that by 30 topics per release and 4 releases per year, and you have consumed 120 engineering hours annually β nearly a full month of engineering time β on documentation support alone.
**Rework and review cycles.** Documentation that moves through multiple review rounds multiplies the effort. The first draft takes 2.5 hours. The review takes another hour. Revisions take another hour. A second review adds more. By the time a topic is published, the actual effort invested can be double the initial writing time.
## A Simple Model
Here is how to estimate cost per topic for your organization. You need five numbers:
- **Writing time per topic** β the average hours a writer spends producing a topic
- **SME time per topic** β the average hours of engineering input required
- **Waiting time per topic** β the average hours of idle time per topic (discounted by 50%, since writers can work on other things while waiting)
- **Blended hourly rate** β the average cost per hour across the roles involved
- **Topics per release** and **releases per year** β to scale up to annual cost
The formula:
> **Cost per topic** = (writing time + SME time + waiting time x 0.5) x hourly rate
With typical numbers (2.5 hours writing, 1 hour SME, 2 hours waiting, $100/hour blended rate), a single topic costs around **$450**. Multiply by 30 topics and 4 releases, and the annual documentation cost reaches **$54,000** β before you count tools, hosting, or localization.
That is just the direct production cost. The engineering time consumed β 120 hours per year in this example β has its own opportunity cost that rarely appears in documentation budgets.
## Where the Savings Are
Once you model documentation as a production system, improvement levers become obvious:
**Reduce waiting time.** This is often the highest-leverage change. Async review workflows, dedicated SME office hours, and better scheduling can cut wait time by 50% or more. In the model above, that saves roughly $6,000 per year.
**Reduce SME time.** Better preparation before SME sessions, self-service information for writers, and structured interview templates can reduce engineering input by 30%. That saves about $3,600 per year and frees engineering capacity.
**Reduce writing time.** Templates, content reuse, structured authoring, and style guide automation can reduce writing time by 20% or more. That saves $6,000 per year.
Combined, these three levers can reduce annual documentation cost by roughly **29%** β and these are conservative estimates.
## Why This Matters Now
Three trends make documentation economics increasingly important:
1. **AI is raising expectations.** Organizations investing in AI-powered support, chatbots, and knowledge systems are discovering that the quality and structure of their documentation directly affects AI performance. Poor documentation does not just frustrate readers β it breaks AI implementations.
2. **Engineering time is expensive.** Every hour an engineer spends supporting documentation is an hour not spent building product. As engineering costs rise, the hidden cost of documentation support becomes harder to ignore.
3. **Content volume is growing.** Products are becoming more complex. Release cycles are shortening. The number of topics that need to be produced or updated per year is increasing. Small inefficiencies in the per-topic cost multiply across larger volumes.
## Start Measuring
The first step is to calculate your own numbers. I built a [Documentation Cost Calculator](/documentation-cost) that lets you plug in your organization's numbers and see the results β cost per topic, cost per release, annual cost, engineering time consumed, and potential savings.
It takes about two minutes. The results tend to start interesting conversations.
If the numbers surprise you, that usually means there is a significant improvement opportunity. A short diagnostic conversation can help determine where the biggest leverage points are in your specific workflow.
---
*I help documentation teams understand and improve the economics of their content production. If you want to discuss what the numbers look like for your organization, [book a short call](/book) or [email me](mailto:mattias@improvementsoft.com).*