How to Manage Latest Versions with Pretty URLs - Fluid Topics

Category
How To
Audience
public

Business need

In a world where SaaS solutions are increasingly popular, users often look for documentation about the latest version of a product.

They can manually select the latest version of a document while consulting it in the Reader page as follows:

Latest version tag

However, it would be easier if links to documents would always open to the latest version, unless specifically configured to point to an earlier version. To make this happen, administrators need a way to ensure that links to the latest version of the documentation remain stable throughout all future product releases.

Overview of the solution

To implement the solution, an administrator with the ADMIN or KHUB_ADMIN role must configure a Vocabulary, configure an Enrich and Clean rule for that Vocabulary, and define Pretty URL templates.

Procedure

The procedure requires the administrator to access the following tabs of the Administration interface:

  • Vocabularies to create a list of synonyms.
  • Enrich and Clean to configure a rule.
  • Pretty URL to configure templates.

Configure a vocabulary

In the Vocabularies administration interface, an administrator can define Latest as a synonym for the latest version of your product as follows:

  1. Prepare a CSV file based on the following example, keeping only Latest and replacing 3.11 with the value corresponding to latest version of your product.

  2. Upload the file in the Vocabularies administration interface. The following image shows the result after Antidot's technical content team uploaded their file to doc.fluidtopics.com.

    Example of adding CSV file in the Vocabularies administration interface

  3. Select Reprocess in the Vocabularies administration interface to apply the new synonym to all content in the Knowledge Hub.

If not defining a synonym in American English, change the value for the afs:lang metadata in the CSV file before uploading it.

Configure an Enrich and Clean rule

In the previous step, an administrator configured 3.11 and Latest as synonyms. If they do not configure an Enrich and Clean rule, Fluid Topics will display both 3.11 and Latest alongside each other. Configuring a rule is necessary in order for the value Latest to replace the value 3.11.

When configuring the Enrich and Clean rule, clear the Apply hierarchy and Remove unclassified values checkboxes if they are selected.

Define Pretty URL templates

To complete the process, the administrator must configure at least one Pretty URL template with a metadata requirement set to the original value for which Latest is a synonym.

In order to get the most out of Pretty URLs, it is best to create at least one other Pretty URL template for content that is not the latest version. This is similar to Step 1, but without the metadata requirement.

Example

This example travels back in time to when Fluid Topics version 3.10 was released. For the occasion, Antidot's technical content team had to configure doc.fluidtopics.com so that the Pretty URL to the latest version of a document would be doc.fluidtopics.com/r/<document_title>, while the Pretty URL to a previous version of the document would be doc.fluidtopics.com/r/<document_title>/<product_version>.

Here is how we made this happen:

  1. In the Vocabularies administration interface, download the file corresponding to the Latest Version vocabulary.
  2. Delete the value 3.9 and replace it with the value 3.10.
  3. Upload the updated file in the Vocabularies administration interface.
  4. Reprocess.
  5. In the Enrich and Clean administration interface, make sure there is a rule for the Latest Version vocabulary and that the checkboxes are cleared.
  6. In the Pretty URL administration interface, update the metadata requirement for the ft:title template by replacing the FT_Version = 3.9 metadata requirement with a FT_Version = 3.10 metadata requirement.
  7. Reprocess.