Multi-source capabilities with extensive content format support
Even though you start with a tactical project dealing with only one type of content, you need to think ahead if you want to be prepared for a variety of use cases and stakeholders. Make sure the dynamic content delivery solution can support multiple and diverse input streams, as you identify all data sources that contain information that could be beneficial to users.
Content enrichment capabilities
Not all content is born alike. Therefore, to deliver consistent information, particularly in a multisource environment, you need tools to clean, align, and enrich the content—particularly the metadata. Because building content processing workflows can be complex, make sure that the dynamic content delivery solution you select offers the necessary functions and can be extended.
Top-notch search engine
This is the most important aspect of a dynamic delivery solution. Regardless of the money you spend in creating content, if you can’t find it, it doesn’t exist. On the other side, burying users with tons of irrelevant content won’t serve. The search engine has to be:
Semantic: support for grammar and synonyms
Full-text: every bit of every document must be indexed
Tuned, tunable, and versatile: relevance tuning is an art, so it has to be good out of the box, but it must be extensible so that additional parameters can be part of the ranking equation (think about user profile, document popularity, freshness, etc.)
Faceted: filters are automatically extracted from the metadata and can be offered to users for narrowing down their search
Suggestive: with type-ahead suggestions (autocomplete)
Typo-tolerant: the spell checker must be capable of learning
Explicit: each result must show why it’s in the list with keywords and synonyms highlighted
Multilingual: all the above capabilities must be equally good in any language that matters to you
Fast: millisecond-quick, regardless of the traffic
Efficient documentation reading
Once the user has found the info, how easy is it to read, to navigate inside the document (particularly large books), to follow internal and external links, to retrace your steps…? Is multimedia content rendered correctly, do large images and vector graphics have zoomability? Can you tune the look and feel of the content to match your branding?
Online content interactivity
Bookmarks, Alerts, Rating, Annotations, Feedback, Personal Books… features that allow you users to customize your content are essential. Pick only the ones you need: too many bells and whistles may clutter up your UX. Define what makes sense in your situation and to your users.
Multi-device, multi-channel publishing output
Of course, the user interface has to work perfectly on common connected devices (laptops, tablets, smartphones), so it needs a responsive interface. Integration capabilities for other solutions such as customer helpdesk tools are essential. Inline/in-device help, chatbots, or augmented reality are not just buzzwords; they are our tomorrow. So, your Dynamic Delivery platform has to be future-proof, not just by tossing in APIs, but by giving you ready-to-use add-ons and extensions.
Open and turnkey publishing solution
You don’t want a bare framework and have to spend months developing something that will need to be revamped anyway in 18 months because everything is evolving so rapidly. Therefore, make sure that the solution you choose is:
Turnkey: it provides you with 90% of your needs in matter of days or weeks. It comes pre-tuned, ready for your brand.
Open: it offers connectors, add-ons, modules, APIs, etc. It can be extended and it talks to other products so that it can be integrated into your IT landscape
Evolving: it has a vision and a roadmap, with the ability to follow the trends and needs. AR, VR, virtual agents, predictive… you’ll be prepared.
Data driven documentation
Tracking users’ behavior while searching and reading is a unique opportunity to learn about them, their problems, and your products. But for that, analytics needs to be tailored specifically, not by regular web analytics tools. Check the capabilities of the dynamic content delivery solution, how it tracks and logs, what metrics it provides by default, if it’s extensible, and how the derived insight can enhance your customer support strategy (data visualization, personalization, predictive, etc.).
Online documentation security
Should be by design at the core of the dynamic content delivery solution (not as an added layer that can be bypassed). It should be everywhere, from search suggestions, to facets displayed, to results and documents accessed, enforced through each web service and every interface. SSO integration with support of multiple simultaneous backends must be ready out of the box. The solution should also provide mechanisms for mapping user profiles to content metadata.
Content publishing regulation compliance
Regulations are putting more and more pressure on every industry. Which ones apply to you? Do you have users in Europe? Then you must comply with GDPR for data privacy. Or with Privacy Shield for US users. What about WCAG for accessibility? The list is not going to get any shorter, so it pays to be prepared.
Or “The world is not perfect, but it’s not a reason for not trying to make it better.”
In a previous blog post, we explained how we manage releases in Fluid Topics but it didn’t tell you much about how we decide what we put in these releases, how we make tradeoffs in the roadmap, and who makes the choices.
This is certainly the most strategic, interesting and yet frustrating exercise for a software vendor.
- It’s strategic because it shapes the product, defines our positioning, and enables (or hinders) go-to-market options.
- It’s interesting because it forces us to examine, sort, and articulate all the demands coming from the different stakeholders, whether internal or external (our clients, partners, prospects).
- It’s frustrating because, as Gide said, “to choose is to renounce”. We would dream of being able to develop all the requested improvements and new features right away, without having to postpone any. But our resources are limited, and we have to make choices. Not to mention some technical dependencies (feature A requires feature B to be implemented before).
Interestingly, each internal stakeholder —customer support, professional services, R&D, sales, product manager— represents a force driving the development of Fluid Topics, hence of the company, in one specific direction, and finding the right balance between these forces should propel us with optimized efficiency.
So how do we choose?
Because we develop Fluid Topics for you, we had to find a way for defining the short-term roadmap (3 to 5 months) that is applicable and explainable. We have opted for a game coming from agile methodology called “Buy a Feature”. Here is how it works. As said, we have 4 groups in the company representing different sets of stakeholders with different needs and expectations:
- The Support team represents existing customers and their demands for improvements (the so called “feature requests”).
- The Professional Services team represents the new customers and the on-going projects, focusing on features that are needed for the go-live.
- The Sales team dreams of functions that would ease the sales process, increase the ROI and unlock market segments.
- The Product team defends the long-term vision and the major innovations that nobody has (yet) asked for.
Before each session (2 to 3 times a year), each team proposes the list of features that it wants to be done in the next 4 to 6 months. The complexity of each feature is evaluated by the dev team so that it has a cost. As you can imagine the total workload of the 4 combined lists represents at least 3 times the capacity that we have.
Here starts the game
The teams gather and each is given the same amount of money. But the total sum of money distributed is far less than the sum of all the features, and slightly less the total number of development days available in the next 6 months (roughly 80%). With that money each team will buy features. Because a team doesn’t even have enough money to buy all its own proposed features (maybe 25% of them) it will have to negotiate and to join forces with other teams to buy features. It’s a very interesting moment and certainly one of the biggest benefit of the game because each team explains the value that a feature brings, thereby sharing its concerns and perspective. This helps aligning the vision and creates transparency and engagement.
Once the final list if settled, it is ordered according to technical, organizational and commercial constraints. We are then able to update the roadmap and to communicate it to our customers. We know some of them may be frustrated not seeing their request or suggestion scheduled, but since it’s impossible to satisfy everyone, at least we know that we have a method that is balanced, explainable and transparent.
So don’t hesitate to reach out to us to feed the roadmap and to help us develop and refine our vision. We cannot guarantee that every request will be done immediately, but we can promise that we will always listen and make our best to provide you with the best dynamic content delivery solution on the market.
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.
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.
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.
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:
- 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.
- 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:
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)
- No risk of missing any information since, by default, each and every byte of content is included in the search.
- 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)
- Consistent search results and easy user experience, as only French results are displayed.
- 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
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).
- 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.
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.
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.
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?
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.
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?