Blog

← Back

Partners Blog Series: Fluid Topics

As part of our best-of-breed approach, IXIASOFT partners with many outstanding tool and service providers. This post is the third in a series that features our various partners. 

As technical writers, we put a lot of effort into producing high-quality documentation that will support our readers as they work with our products. But even the most amazing documentation is useless if readers cannot find it, quickly get the answers they need, or adapt it to their needs. Great documentation needs a publishing environment that can help take it to the next level. 

This is exactly the kind of leverage that Fluid Topics provides.  Fluid Topics is a dynamic content management solution for publishing technical information. It takes your documentation—in any format, from DITA files to Word documents to videos—and publishes it to its simple and interactive online publication system where it can be searched, annotated, modified, and even re-packaged by your users. 

This post presents Fluid Topics and its features. In order to get a better idea of the product and see how easily it integrates with the IXIASOFT DITA CMS, I thought it might be interesting (and fun!) to actually try out Fluid Topics with our DITA CMS User Guide. 

Integrating Fluid Topics with the IXIASOFT DITA CMS

Fluid Topics includes two main areas: the user portal, where users access your documentation, and the Back Office, where you publish and manage the documentation. To upload documentation, Fluid Topics provides a simple interface through the Back Office. You can upload any type of files: DITA, FrameMaker, Word, PDF, pictures, video, ZIP, and much, much more. 

In my case, I uploaded the DITA files and images for the DITA CMS User Guide. DITA CMS integrates with Fluid Topics through our Output Generator, as shown below. To upload the files for a document, you create an output type that extracts the map and its children from the DITA CMS Content Store and pushes it to the documentation portal through the Fluid Topics Back Office. The output type specifies the information to connect to the Back Office domain, including the IP address, user name, password, etc.

Integrating Fluid Topics with DITA CMS was very easy. In less than one hour, I was set up and could publish to the Fluid Topics site directly from our Output Generator. I created a new output type that connects to the Fluid Topics Back Office, called Publish to Fluid Topics. I then selected my map in DITA CMS, generated the output using the Publish to Fluid Topics output type, and voilà! My documentation was uploaded within a few minutes.

User’s perspective: Working with the Fluid Topics user portal

Fluid Topics provides an intuitive user portal that has three main areas: The home page, the search results page, and the reader page.

Home page

The home page is the main landing page, which allows users to search through your documentation set. Every element of the user interface can be customized to reflect the branding of your company, providing a smooth transition between your website and the Fluid Topics documentation portal. 

You can provide promotional material on the home page: important messages to your users, information about new products and releases, links to training material, or even display seasonal greetings:

Partners Series: Fluid Topics images

One of the strengths of Fluid Topics is its very fast and semantic search engine, which provides smart autocomplete, suggesting content from your documentation set based on the user’s input, as shown below:

Partners Series: Fluid Topics images

If the search phrase entered contains typos, suggestions are offered to the users. 

You can also use the search keywords entered by the user to display promotional material on the Search results page. For example, let’s say that your company is hosting a webinar on DITA 1.3 features. You can configure the home page so that when users search for “DITA 1.3”, the details of the webinar are displayed on top of the search results. 

Search results page

Once users enter their search keywords on the home page, the results are listed on the search results page: 

Partners Series: Fluid Topics images

Another strength of the Fluid Topics solution is its use of facets (left pane), which can be used to filter the search results. These facets are built dynamically from the metadata available in your source files. For DITA files, the contents of the <bookmeta>, <topicmeta>, and <prolog> elements are used to create the facets, and each topic inherits the metadata of its containing map. By default, all metadata is included, but you can configure which ones to display to your users. For files that do not include metadata, you can associate a control file that will define the facets, so all your content can benefit from the same filtering capabilities.

Reader page

When users click on a search result, the topic is displayed in the reader page and is provided in context of its containing map:

Partners Series: Fluid Topics images

A very interesting feature of the reader page is that it doesn’t simply display the topic, as with most HTML outputs. Instead, it loads the preceding and following topics so that you can easily navigate the documentation through an infinite scroll mechanism. As you read the document, the surrounding topics are loaded dynamically. This is extremely useful for installation-type procedures, where users often need to go through many pages to perform the installation. In most systems, they have to open a topic, perform the procedure, and click next to get to the next procedure. With Fluid Topics, this is all very, well, fluid. 

The user portal also uses a responsive interface and can be displayed on any type of device, including tablets and mobile phones.

Allowing users to build their own knowledge base

Most products now provide a very complete and detailed documentation set, which means that users sometimes need to go through hundreds of pages to find what they need. And very often, they only need and use a subset of all the information available, depending on their roles. 

With Fluid Topics, your readers can create personal books from a set of topics that they use frequently. This way, they can quickly find the information that they use regularly. And because these books link to the existing topics, instead of duplicating them, the personal books are updated automatically when you update your documentation set. Users are always working with the latest version of the documentation, even in their own personal books. How cool is that?

These books can be easily modified, saved as HTML, or printed to PDF. Fluid Topics is also working on a feature to share these books externally. Imagine how much your tech support team would love this feature: Instead of solving tickets by writing detailed messages, they could simply create a personal book with the documentation that solves the issue and share this with your customers. 

Back-Office perspective: Everything you always wanted to know about your documentation (but were afraid to ask)

In addition to the user portal, Fluid Topics provides a Back-Office that includes tools for monitoring the portal and providing analytics. I couldn’t possibly describe all of the Back-Office features in a single post, so I picked the three that, as a technical writer, I found most important since they provide crucial information about how your users are accessing the documentation. 

Hit Parade

In a single view, you can see the most frequent search expressions, the most clicked documents, and the most frequent facets used by your readers to access the documentation, as shown below:

 Partners Series: Fluid Topics images

This information helps you understand how your users are accessing the documentation and determine which areas of your documentation are most frequently used, and thus where you should put additional focus. 

These analytics provide very valuable information not only for your documentation but also for your software: a feature or procedure that is frequently searched may indicate that users are struggling with it and the software may need to be improved. 

The most frequent facets show how users like to filter the results. Since the facets are built from your metadata, this tool provides useful information for determining the type of metadata that should be added to your documentation.

Vocabulary

This information can also help you build Vocabularies for your documentation portal. Vocabularies allow you to configure list of synonyms or more advanced hierarchical taxonomies so that you can correlate the search terms used by your readers to the actual terms used in your documentation. For example, between DITA CMS 3.4 and 4.0, the term docbase was replaced with the term Content Store. Users searching for “installing a docbase” would not be able to find topics about installing a Content Store, even if this is the procedure for which they are looking. 

Last, but not least… 

It’s great that we know how users are using your documentation, but now the most important question might be: which documentation are your users *not* finding?  Fluid Topics provides that information in the Queries tab, which lists the queries that did not generate any results. This can indicate that:

  • Some areas of your software require additional documentation
  • Metadata is inadequate or missing
  • Your readers are using a different terminology than you expected to access your documentation

This is crucial information that you can then input back into your documentation, increasing its value and ensuring that the documentation is effectively used by your users. 

In summary

I really enjoyed working with Fluid Topics and was impressed by how easily it integrated with the IXIASOFT DITA CMS. 

For more information

Visit www.fluidtopics.com to learn more about Fluid Topics, its use cases, benefits, or to schedule a demo - you can even calculate your estimated ROI or create your own account to try out their features!

About the author:
Nathalie Laroche
Lead Technical Writer at IXIASOFT and author of extremetechwriting.com. I love and thrive in very technical projects and actually get excited about documenting code and creating API docs. Follow me on Twitter @NathalieLaroche!