Blog HomeBlog Archives:

technical documentation publishing - fluid topics - knowledge management software

Upload your content from oXygen to Fluid Topics in one click

Oxygen XML Editor

oXygen is one of the most popular tools for authoring structured content, particularly in the DITA community. With the support of Syncro Soft — the company behind oXygen — we have developed a plug-in that allows oXygen enthusiasts to publish content in one click, directly from the oXygen interface to Fluid Topics.

See how simple it is: a “Publish to Fluid Topics” button is displayed in the oXygen DITA Maps Manager window, and in the right-click menu.

Just click on any of these, and the plug-in does it all for you: it collects all elements needed (map and DITA files, images), creates a package and uploads it securely to your Fluid Topics instance.

Regardless of which back-end storage you use with oXygen (file system, Git or SVN version control system, CMS, …) you can publish directly from your favorite authoring environment. As soon as you have validated your edits, they can be online within seconds.

If you have multiple Fluid Topics instances, one for production and one for staging content for example, this is also handled by the connector: you can create and manage multiple publishing profiles, and select the one to use at upload time.

As for installing the plug-in itself, it takes less than a minute. It just requires oXygen version 18.1 or above. If you are already a Fluid Topics customer and you are interested, contact us and we will be happy to provide you with the plug-in.

If you are an oXygen user and are thinking about how to elevate the value of your nicely engineered content, it’s time for you to look at dynamic delivery and test Fluid Topics. It will transform your world!

 

Special thanks to George and Radu from oXygen for their support and friendship.

books technical content

You talkin’ to me?
Language Management in Fluid Topics

In this blog post, we sift through the complexity of multilingual content delivery, especially when not all documents are translated and available in every language.

The situation

Your technical documentation is published in multiple languages: 2, 10, even 20 or more for some of you. The easy case would be to have all documents — meaning here any piece of content such as topics, files, images, entire books, etc. — existing in every language and always in sync. But we know that the reality is far from being that simple.

Usually, your tech writing team creates content in one reference language. Let’s say English to keep it simple, because it’s the lingua franca of technical documentation and true at 90%. This could mean that even if an expert provides some content in another language, it is likely translated in English. Let’s call it the Reference Corpus.

In this example, our reference corpus is made of 20,000 topics assembled in 100 manuals.
In this example, our reference corpus is made of 20,000 topics assembled in 100 manuals.

The challenge

You are a global company with some end-users who are not speaking English. Let’s say they speak Japanese and French. You have two possibilities:

  1. You translate everything -> “English Corpus” = “French Corpus” = “Japanese Corpus”.
    Then it’s easy. You are sure that whatever language they speak, your users have access to all information. Your users read in their native language, and you can automatically set the appropriate search language based on the browser language or the user preference.
  2. Only a subset of the entire corpus is translated (the content dedicated to end-users), and part of the documentation is not translated but available only in English (the content for experts and partners for example). Even worse, each country adds some documentation that exists only in its language (regulatory and compliance notices, local features, etc.).
    The situation looks like this:
    Translated_Corpus

Now the question is very simple: How should your portal behave? When a user searches for information, what content blocks (see image above) should be looked upon?

Let’s keep it simple and say that our user, Jean, is French. Jean chooses the French UI. As in case 2, part but not all of your content is translated into French. Jean needs to know how to fix a component and runs a search for “X124 installation”. What should happen?

A- The search is run on all documents (En, Fr and Ja)

Translated_Query

Pros:

  • No risk of missing any information since, by default, each and every byte of content is included in the search.

Cons:

  • Results are possibly duplicated, or even irrelevant. Keywords exist in different languages (here in Fr en En) and an ambivalent query could lead to misleading results.
  • Returning results in a language a user does not understand is inappropriate. How would you feel about a page stuffed with Japanese text if you don’t read Japanese? Surfacing unnecessary and overwhelming information creates a poor and inefficient user experience. Users could refine their searches by filtering in or out desired languages. But, why not make it automatic (see next case)? (see next case).

B- The search is run in one selected language (Fr for Jean)

Not_Translated_Query

Pros:

  • Consistent search results and easy user experience, as only French results are displayed.

Cons:

  • Possibly missing information: Some content has not been translated into French and exists only in English, which means that some critical information relevant to the situation may be missing.
  • Even worse, the search could return “0 result”, making the user believe that there is nothing to help him. And, the probability of having no search results is increased significantly.

We see that both ways of searching are causing problems. And, the intermediate approach of searching in the French and English corpus (user and reference languages) leads to the same issues described in A. Then what should we do?

It’s obvious that the search should run on a set of documentation made of the French elements plus the English elements applicable but NOT translated. Let’s call this the Full Virtual Corpus:

  • Full, because it now encompasses all content relevant to a user
  • Virtual, because it is made of different blocks of content from different languages

Full_Corpus

But it’s not that simple. Running a search with French keywords on English content does not make much sense, as the keywords and the content won’t match. However, we can assume that the user reads English as the choice of not translating everything was made, because this specific content is meant for people used to English (e.g. sysadmin in IT).

Then there are two ways of doing it:

  • Low-tech: Execute the query on the French Corpus. Warn the user that some content may be missing and that they should also do a query with English keywords (and run the query on the English corpus, or on the English content part of the Full Virtual Corpus).

Query_Suggest

  • High-tech: Automatically translate the user query and run two queries at the same time … with the initial keywords on the French subpart of the Full Virtual Corpus and the translated keywords on the English subpart.

Both_Queries

The high-tech approach is what should be done, but it can be quite complex. How do you translate the query? Multiple solutions:

  • Rely on external generic translation web services. Certainly the approach requiring the least amount of work, but it may lead to poor results, as those web services are not aware of the specificities and vocabularies of your domain and content.
  • As users search with keywords and not phrases, you can provide a dictionary of terms — mixing generic dictionaries and specific dictionaries for your business term — and do word-for-word translation. This requires significant work, as you must create and maintain those dictionaries.
  • Here is the trick: Those dictionaries already exist! They are the translation memories. Since part of your content has been translated, this has generated aligned dictionaries of terms and expressions. Just use it.

Important: Even if we know the language of that user (from their browser or preferences), it’s important to keep in mind that there is a difference between the UI language and the content language. The UI may be available in 10 languages, but your documentation only in 3. A German user may set their UI to German but still has to select a different “preferred language for content” if none of your documentation is available in German (as in our example). Either you declare a default fallback language for German (“if UI in German than search in English”), or the user selects it manually.

As you have read in this blog post, multilingual content delivery is not that simple. It doesn’t just mean that you must index all content. It requires understanding and technology to best match your situation. Being on the edge of dynamic content delivery, Fluid Topics already embeds the tools that you need. We continue to research and investigate with our partners specialized in translation, such as WhP, to always push the limits and make your content the cornerstone of your customer support strategy.

secure publishing solution - Fluid Topics

How To Secure Access To Technical Content

Among the new features of Fluid Topics version 2.7 release, access control is certainly the trickiest one and it deserves some clarification. Most of our clients are interested in securing access to their content. Some of the motivations and use cases for secure access include:

  • Make part of the documentation publicly accessible, while the rest is limited to customers.
  • Centrally expose all content related to product support, but restrict access to some content to internal users only, based on fine-grained roles and profiles such as support agents, subject matter experts, field operators, etc.
  • Limit access to preview content for upcoming products to partners and resellers.
  • Deliver customer-tailored documents: some content may be specific to one customer based on its product configuration.
  • Make part of the content —such as training material— accessible on a subscription-based model.

Whether the need is immediate or planned for future implementation, this capability should be part of your checklist when searching for a content delivery solution. In fact, many companies choose Fluid Topics for its incredible flexibility and ability to cope with various situations.

To set up this security mechanism, clients often have to answer many questions and sometimes solve functional and technical issues. Even if Fluid Topics makes it easy, there are two issues that clients must address.

1. Understand the difference between authentication and authorization.

Authentication consists in knowing who the user is, and making sure that he is who he claims to be. This is usually achieved in the login phase with a username or email, plus password. In more demanding environments, this can be accomplished through security devices such as secure cards. To avoid forcing the user to authenticate again, Fluid Topics can connect to SSO systems and check if the user is already authenticated. Fluid Topics also supports out-of-the-box multiple standard SSO protocols —such as SAML, OpenID, OAuth— and can be extended to support proprietary protocols.

customer portal support with fluid topics

Authorization determines the permissions of authenticated users: resources they are authorized to access and features they can use. Access rights are usually modeled by a set of profiles and groups a user belongs to, and user credentials are authorized by obtaining a list of those profiles and groups. Authorization requires organizations to answer essential questions:

  • What is our permission model?
  • What groups, profiles or roles already exist?
  • Where are groups and profiles defined and stored?
  • Do groups and profiles match what we are trying to achieve in terms of content access? Or do we need to create new ones?

Example: You want to limit access to some content to your certified partners and resellers.

  • Do you have such groups defined? Are you sure that the corresponding users are properly tagged as being part of those groups?
  • Where is this information stored? Is it already in the directory used for access control? Or is this information managed in a separate application such as your CRM?
end users access technical documentation

User credentials are usually provided as part of the SSO dialog (through SAML assertions, for example). If the group’s definition and membership exist in an application such as your ERP or CRM that is not connected to your security infrastructure, you will either have to connect these systems or expose them through a Web Service. If the credentials are already defined in the directory used also for authentication, you’re ready to go. This is an issue to investigate with your IT department.

2. Define the relationship between credentials and content attributes.

The groups and roles used for defining user credentials usually don’t match the metadata existing on the content side. This is normal, but still it’s an issue.

Content such as technical documentation is usually written in advance, independently of delivery strategy and regardless of the security mechanisms that may be put in place. This content is usually tagged (type, related product, version, tasks, audience, etc.) with some metadata put inside the content, while other metadata is defined and stored “outside” the content, such as in the CMS.

metadata technical content - dynamic delivery

The decision to include metadata inside —when metadata are content-related and not dependent of the context— or alongside a piece of content, is very important but it is not the subject of this discussion. In both cases, metadata is usually not included in the groups used for defining user credentials, and it’s a good practice not to do so. In some cases, you may find the profiles you want to define for content access may not even exist in your directory.

Imagine that you have 10,000 topics and that you have to tag 20% of them as “partners” because they are accessible to partners. One day, marketing decides to create Silver and Gold Partnership levels. Do you think it make sense to manually modify the tagging of 2,000 topics? And by the way, the group “partner does not exist. Instead, the CRM holds attributes such as reseller or integrator.

This is a typical situation you can resolve by mapping between the user groups and the existing metadata. Fluid Topics makes it easy to dynamically and flexibly use mapping capabilities, but you must define mapping parameters based on your system.

Remember: securing access to your content will require you to answer two questions:

  • What are the existing credentials and how are they made accessible?
  • How do the access groups map to the existing content metadata?
For more information about the other features of version 2.7, see the release note.

Please give this new version a spin and let us know what you think. Comments are always appreciated and encouraged.

search and find with fluid topics

Fluid Topics 2.6 boosts the search experience

We’re very excited to share today’s release with you. The new version of Fluid Topics delivers major improvements to the search experience. We’ve boosted the efficiency of information access by providing more knowledge objects in the unified search, the ability to preview content from within the search page, intelligent spell checker, and other features to improve the user experience

Version 2.6 also brings a very unique capability called Book Dynamic Filtering.

Documentation for Multiple Software Versions

Consider this case: a software vendor has its product available for on-premises installation in RedHat or Debian Linux distributions. Moreover, the product can be deployed on a single server or on multiple servers for horizontal scaling and high-availability. It can also use different database back-ends, such as relational or noSQL storage. With eight combinations available, the resulting documentation will include two options:

  1. Eight different manuals, published separately. This is costly to generate, especially with more options such as versions, it could include 30 or 40 documents. In addition, you have to ensure that users can easily find the right version.
  2. A single large manual that includes all information. Such a cumbersome manual will include a large number of subsections —“3.2.4.1 for Debian”, “3.2.4.2 for Redhat”, “3.2.1.1.1 single server”, “3.2.1.1.2 multiple server”— and multiple links. This sort of large catch-all manual is a potential source of errors, user mistakes and high support costs.

When searching for information, users may be offered facets for filtering and targeting the platform matching their situation.

facet-platforms

When they rapidly spot the proper content, they click to open the manual and access the entire installation procedure.

But when users see that the book contains indications for all platforms and architectures, they can become frustrated knowing they have to struggle to find the proper content.

toc-platforms

How Fluid Topics Book Dynamic Filtering Improves the User Experience

Book Dynamic Filtering solves this issue in the most elegant and efficient way. For example, facets that the user selects during the search phase are transmitted to the Fluid Topics embedded reader, which automatically filters the book accordingly.

facet-to-reader

The manual’s table of contents and its content looks as if it was generated specifically to match the user’s needs, with a property box displaying the active parameters.

book-properties toc-filtered

All of these functions are performed dynamically in real time by Fluid Topics. You don’t have to worry about generating multiple books or fear that your users won’t find the exact version they need. That’s the magic of Fluid Topics: true dynamic publishing delivered.

For more information about the other features of version 2.6, see the release note. Try out the latest update and let us know what you think.