Madcap Flare Knowledge Base
Amalia Antill
The customer, a pioneer in access management, was having trouble maintaining their brand experience consistent between MadCap Flare and Salesforce Experience Cloud. They wanted to build a new knowledge base in MadCap Flare and migrate their existing content from FrameMaker to MadCap Flare to deliver a seamless UX.
LinkedIn and 3rd parties use essential and non-essential cookies to provide, secure, analyze and improve our Services, and to show you relevant ads (including professional and job ads) on and off LinkedIn. Learn more in our Cookie Policy.
For the past months I've been working on MadCap Flare together with our technical writer Magdalena and our design team at Bynder. For those who don't know what MadCap Flare is, it is a tool for technical writers that can help you create and maintain online knowledge bases or infocenters. Flare has some nifty features that save time and allow you to automate certain processes.
However, after we published our new Flare-based knowledge base, it became clear that while it is a good technical writing tool, what Flare lacks is a solid SEO support. Our SEO team noticed frequent errors coming from the knowledge base in the improved site crawler tool from our friends at MOZ. Every crawl resulted in duplicate pages, duplicate titles and missing canonical tags.
Now, this is a fairly normal error if a script is missing some html tags and uses parameters. I needed to fix this, and I did, but it wasn't as smooth and easy as it should have been. The solution required access to the published output location and a little scripting.
I took a closer look at the URL's and noticed a pattern. After user would run a search in the knowledge base, all the results got an added ?Highlight=search addition. The ?Highlight= parameter highlights the words found on the page.
Unfortunately the ? parameter after the URL can potentially change the page content. Even though the content of the page (except for the highlighted words), the title, and the description are still the same. So in the end it can be seen as duplicate content by crawlers.
The normal way to solve duplicate page errors and also SEO best practice is to add a canonical link to every page. A canonical link looks like this and can be placed in the section of your page (with the URL being the current page url without parameters):
In this way Google or other crawlers knows the page with the ?Highlight= parameter has the same content as the one without it. If you still don't understand what this tag exactly does, please have a look at this article about canonicalization and how to use it to get rid of duplicate pages.
A quick search on the MadCap Flare forum resulted in finding a client suggesting a Javascript solution that would add the canonical to the of the knowledge base. Unfortunately, not all crawlers are able to execute Javascript after getting the initial contents. So this was not a viable solution.
Good idea! I tried to set the link manually, but it was stripped from the output. This was disappointing. So I tried setting it it dynamically to be future proof and to avoid manual input and hoping this dynamical version wouldn't be stripped. Although MadCap Flare supports system variables, there was only one variable for the SourceFile (filename.htm) itself, not for the full path. I just had to try and see if it would work.
This output also got stripped in the output of the knowledge base. Just out of curiosity I tried adding only the variable to the individual topic and/or master page to see what would happen (so there was no manual input in the href part):
This canonical did come back in the output. I thought I had a winner, because it wasn't stripped, but the page needed a tag with the full path to be fully valid. Unfortunately the base tag got stripped from the output and I was back to square one.
We decided to have a go at contacting support and our technical writer told me that the canonical tag was currently not supported by Flare and only if more customers wanted it, would it get a higher priority on the roadmap. I guess not everyone is aware of this tag and its useful properties. But I wasn't ready to give up and wait for a solution.
Note: it is still a workaround until MadCap Flare supports it in the general output. But I'm happy to show you this temporary solution, because I think every company that uses MadCap Flare should have these canonical links in place:
I know the meta rel="canonical" is not the correct notation, but it won't be stripped from the output and will work in the output. Also our technical writer can easily add this tag when creating a new topic.
3) Login via SSH to your final published output and run this search and replace command (the /usr/bin/find location and your output location vary depending on your distribution and settings) or ask your DevOps team to help you with this one:
4) Set up a cron job to run this replacement rule. Cron is a Linux utility which schedules a command or script on your server to run automatically at a specified time and date.
I hope you liked my second article! If you use MadCap Flare, and a lot of companies do, please share it with your Technical Writer and the DevOps team so you too can have valid canonical links and make the most out of your knowledge base with the improved crawling support.
Knowledge bases are often used for customer product documentation, API documentation, software documentation, to help customers self-serve, or support internal staff. The software behind these kinds of sites are known as knowledge base software.
A Help Authoring Tool is also software used for producing help content, which is intended for publication on a knowledge base and beyond. A HAT is more like a content database, since its purpose is to store your content as files that can be reused, and marked up in a way that defines their correct usage.
Often HATs are used in the enterprise because they help companies comply with certain regulations and produce large volumes of documentation. For example, many companies in the medical and pharmaceutical industries are legally required to produce a particular number of pages of documentation for their products.
Single source publishing means that you can produce multiple output formats and versions from one shared text base. That means you write your documentation once and export it to multiple formats, saving untold amounts of time and effort.
There are quite a few knowledge base software solutions now on the market, including our own KnowledgeOwl. There are some key differences in functionality between them, and KnowledgeOwl offers the utmost flexibility for your business.
KnowledgeOwl is a great piece of software that does exactly what it needs to do, and nothing more. It's thoughtless to the point of never being in your way, allowing you to focus on writing and managing articles instead of spending time messing with options and configurations.
One of the main differences between the two types of software is price. Knowledge base software typically comes a lot cheaper than your typical HAT. This is partly to do with the fact that HATs are more common in the enterprise, as they help fulfil enterprise requirements.
Knowledge base software is also usually sold as SaaS (Software as a Service), on a subscription basis. This makes it more affordable for smaller businesses. SaaS solutions tend to have more user-friendly interfaces, and liberally use the latest design principles for better User Experience.
A HAT may not be a web publishing solution in itself, but rather a content development tool. This means you will need to combine your HAT with another system if you want to have a website for your knowledge base. You could export your documentation from a HAT and import it into a knowledge base tool.
Technical writers use both types of tools in different situations, but knowledge base software is geared more towards self-service or internal Knowledge Management. It provides a standalone website and CMS publishing system.
Know the difference between the tools to invest in the right solution for your team. Teams looking to publish documentation on a website may opt for a knowledge base tool. Teams who need to develop content for a variety of platforms should consider a HAT.
Many technical writers and developers are concerned with creating technical documentation for their users. These content creators want to teach customers how to use their product, comply with regulations, and help them seek assistance when they run into trouble.
MadCap Flare offers the capabilities to single source your documentation and publish to different formats. Topic-based and micro-content authoring gives creators ultimate control when it comes to managing and distributing their documents.
MadCap Flare gives you many ways to manipulate your content, allowing you to create technical documentation, application programming interface or API documentation, software documentation, interactive eLearning courses, learning and development programs and much more. The ribbon toolbar mimics Microsoft Word, giving users an interface that they will be familiar with.
MadCap Flare users can create content once, and then publish instantly to a number of different channels. You can update content in a single location and then re-publish to your preferred formats, giving users a consistent experience and minimizing re-work. This feature also allows you to cater your documentation to different audiences, such as beginner and advanced users.
With MadCap Flare, you can easily manage documentation projects from beginning to end. MadCap Flare allows you to keep track of your progress, and lets you see all items relating to your project at a glance. Project templates allow you to create beautiful web and print-based outputs in minutes.
MadCap Flare gives you the capabilities to translate your documentation into multiple different languages. MadCap Flare supports Unicode language characters, double-byte Asian languages and Eastern European languages, as well as bi-directional language authoring and publishing including Hebrew, Arabic and Persian. Integration with MadCap Lingo gives you support for the translation process.
c80f0f1006