Sairam Venugopalan, Qualcomm
May 15, 2021

Not until so long ago, information developers were hemming content, out of raw engineering source materials and scientific data, in a palatable form for consumption as full-blown printed manuals or wholesome portable books. It is true that several organizations continue to render their product literature as fully downloadable PDFs or compiled help files, alongside modular or layered documentation in the form of standalone topics as Web files. However, most of us will quickly concur that it was fairly easier to manufacture and maintain content for whole-blown containers or publications than to chunk and comb content for modular or tiered topics.

From a writer’s perspective, it’s increasingly arduous to maintain an inventory of topics that are authored afresh for, say, every new product that’s introduced, because of the incessantly burgeoning count of such topic-chunks. I can hear a vehement argument in quick retort that metadata, keywords, and taxonomy terms are vital cues that can assist a writer that’s searching for sardines (a pertinent set of topics) in the ocean (database or repository) of interest. So, the ever-proliferating set of topics shouldn’t be a deterrent?

While it is true that such filter or criteria handle to assist the quest to hone in on an appropriate set of topic-chunks, I can see heads nodding in agreement of how the sheer magnitude of topics we end up churning, as time wears on, turns out to be overwhelming and, even, daunting. Crowded by content that’s mostly matching with one another, barring subtle differences in the text or graphics, often, writers succumb to the rude reality of the futility of such searches. As a trade-off, to wriggle out of the cobweb, a whole new cluster of topics and images are stitched to cater to product delivery. Now, this exercise only adds to the already humungous heap of files and objects that reside in the database.

Rationalization – Articulated with a use case

Consider this case: Cakes and Bakes, a company that sells pastries and confectionaries, have their procedures for preparing all of their delicacies written out in topic-based format. Given that the instructions, right from measuring the proper quotient of raw materials to kneading the dough to readying the oven, up until the point of steaming the spongy cake, are the same for a Pineapple Pastry or a Fruit-and-Nut Flower, a single task would have befitted this purpose. The topping is the only difference for the Pineapple Pastry or the Fruit-and-Nut Flower.

Two separate procedures exist at this point at Cakes and Bakes for Preparing the Base Cake Without the Topping. They were written at different points in time by writing individuals that didn’t realize that a single procedural topic could have sufficed this need. The topics were titled to make them specific to each variant of cake. As the flavors of cakes increased, the number of task topics for largely the same activity kept growing. Not only does this increasing number of topics make the work of writers strenuous, but also results in poor customer experience and performance degradation on the database.

In this scenario, the principle of rationalization can be applied. Identifying content that’s allied or matching, repurposing the information to be generic or agnostic, and reducing the number of diversified topics constitute rationalization. Cakes and Bakes, now, have a single procedure that articulates the process of preparing the base cake, with related links to lead to further information that’s specific to topping and creaming each flavor of cake.

Efficacy of rationalization

Ideally, you’d love to future-proof our content by writing generic or agnostic topics (where appropriate) from the beginning to avoid having to merge or rewrite content later. However, this does not always happen. Most often, you’re left with a situation to either endure an average user experience or rationalize the content.

Rationalization is the process of examining content that applies to multiple entities or objects, updating it and improving it to work for all the identified entities, and presenting it as a consolidated, single topic. This refurnishing process is intensive because it involves updating links, disabling the obsolete topic, and, in some cases, removing an HTML file from the server and asking the Web administrator to create a redirect.

Two primary use cases where you might need to merge topics:

  • Two or more topics contain duplicate content (similar to the one at Cakes and Bakes). You decide to merge them to avoid customer confusion and excess topic maintenance.
  • Two or more spawned topics about the same subject exist. You decide to merge them to reduce needless navigation and also render a consummate explanation.

Are rationalization and topic-sharing synonymous?

A difference exists between the two tenets. Rationalization is a process of taking two or more topics that contain similar information and combining them into a single topic. If the topics apply to the same entity, such as Microsoft Windows OS and Google Chrome OS, the process does not result in a shared topic. It simply results in a unified topic for the single entity. If the topics apply to different entities, the end result is a shared topic.

On the contrary, topic sharing is the process of writing a single software topic in a way that makes it applicable to multiple entities; for example, in our case, carving a conceptual topic that pertains to both Windows and Chrome environments. Ideally, you would never create the second topic that needs rationalizing — you would share the first topic from the beginning

Rationalization is a rough road to tread!

Almost always, rationalization is a hard grind — it has no secret sauce for success. Amidst the regular project grind, it’s hard to find the resources to dedicate to this intensive process along with all our other priorities. That’s one of the prime reasons why you must be careful about mindlessly cloning topics and about writing content correctly the first time — finding the time to rationalize content later can be exceedingly hard as your information reserve keeps mushrooming.

While the intricate and labor-ingrained nature of rationalization is highlighted here only to drive home the point that it isn’t an easy, one-swoop chore, you shouldn’t be shuddering at the very thought of this exercise. Acknowledging and embracing the challenge that this task portends must only propel you to add this feather to your cap of other skills.

Recipe to rationalization

In several daily circumstances, multiple topics already exist that document exactly the same subject. In this case, you might need to merge the topics into a single topic so that your customers will not be confused by having multiple sources for the same information. This consolidation process is called rationalization.

To rationalize different topics that discuss the same subject or entity:

  1. Assess the owners of the topics that you are merging, and contact them as necessary to discuss the change.
  2. Identify which topic to keep and which to discontinue. It’s preferable to retain at least one, instead of creating a third new topic where you combine all the content.
    • If one topic seems more prominent or more useful to customers, keep that one.
    • If you are not sure which one to keep, you can view dependencies for the topics in your XML content management system, and identify which has the most dependencies, and merge all the content into that topic.
    • It will be less work to discontinue the topic with fewer dependencies.
  3. Copy any relevant content from the topic that you plan to discontinue into the topic that you plan to keep, including:
    • Content in the body of the topic
    • Metadata
    • Index entries
    • Keywords
    • Related documentation links
  4. Rewrite and enhance the merged topic as required to accommodate the consolidated content. For example, verify whether you can replace each hardware-specific term, such as an access point or a switch with a more generic term such as device or the platform.
    • If you find that you cannot replace the hardware-specific term with something more generic without compromising the content, examine whether you can indicate that the content in question does not apply to the new device or hardware. For example, “Although you can configure VPNs on Robust Routers and Resolute Routers, you cannot configure them on Rickety Routers.”
  5. Submit the merged topic for editorial review.
  6. Find all the topic-refs that point to the topic that you plan to discontinue and update them to point to the newly merged topic.
  7. Find all the content collections or bookmaps that include the topic that you plan to discontinue and update them to point to the newly merged topic.
  8. If the topic that you are discontinuing has already been published on the website for the release that you are updating, or if it is release-independent, create a server-side redirect for customers who have bookmarked the topic that you are discontinuing.

As this article draws to a close, I trust most of you will allude that rationalization is one of the natural, common-sense facets that must be imbibed and constantly applied during content creation. It isn’t any new revelation, rather, a tonic to keep the stable of topics trim and tranquil.