Select Page

The concept that should underlie your documentation strategy

Abstract: Groups with complex products and documentation, like financial technology developers, should be building content sets on a centralized information model that allows you to treat your content like data components.

Which Version is the Most Recent?

Version control has always been an issue in content creation and management, an issue that can be extremely costly on many levels. When multiple versions of a document exist it rapidly becomes unmanageable. With a legacy authoring system like Word, the only way to share docs during creation is by copying them. Each time this is done, a new version is made and changes in that version are not reflected in other versions. Because of that, version control becomes extremely time consuming and costly. This is a cascading issue:

  • Multiple people contribute and edit without awareness of what changes others are making
  • Each distribution of that content creates a new version, multiplying any issues
  • Once shared, consistency is uncontrollable, as is messaging and quality
  • Understanding the current version can only be managed manually with version #s or naming conventions, leaving no record of past changes. Track changes only works in the version of a doc that has activated it, not across all versions.
  • Updates to text within the doc cannot be made across multiple versions
  • You cannot do a global search across an enterprise for content that resides on desktops or as attachments to emails

And on and on.

It gets even more complex when your documentation is being delivered to other systems using manual export/import. Because of these problems, a requirement for this kind of systems interoperability is increasingly common in larger organizations.

Fortunately there is a solution to all of these problems and it lies in the concept of a ‘single source of the truth’. Let’s look at a definition of this concept:

In Information systems design and theory, single source of truth (SSOT), is the practice of structuring information models and associated schemata such that every data element is stored exactly once. Any possible linkages to this data element (possibly in other areas of the relational schema or even in distant federated databases) are by reference only. Because all other locations of the data just refer back to the primary “source of truth” location, updates to the data element in the primary location propagate to the entire system without the possibility of a duplicate value somewhere being forgotten.”


Building a Central Source for Your Content With a CCMS

In content management, the goal of achieving a single source of truth by using a centralized content repository or database in which all content is stored and where all activity around that content takes place:

  • Authoring
  • Editing
  • Reviewing
  • Formatting
  • Curation for translating
  • Multi-channel formatting and publishing

From this repository the content can be published to multiple media formats and languages, without worrying about its consistency– because there is never more than one version. To achieve this, new tools are required that use entirely different models for the above activity. In our case, the tool is a component content management system (CCMS) whose rules are defined by a standardized architecture (DITA) and file format (XML) that is compatible with various systems and media types.

The Path to a Content Single Source of the Truth

If the concept of a central repository for content creation, management and distribution is compelling, why doesn’t every company use one? Like any disruptive change, moving to structured content in a CCMS has technical and cultural challenges. Though we are major proponents of such adoption, we understand that these issues can be significant. On the technical side, migrating large quantities of technical documentation from siloed desktop systems like Word can be challenging and resource-intensive. This is made more complex by the fact that authoring in a CCMS is handled very differently than in legacy systems. Existing content needs to be broken down into topic categories (Concept, Task, Reference), imported into the new system, and organized with metadata. Only by doing this can that content realize the full potential of structure including reuse, improved translation workflows, easier multi-channel publishing, and more. While the basics behind this are beyond the scope of this post, there are processes for moving to structured content systems and vendors who provide such services.

The greater challenge, in our experience, is the cultural one. Your tech writers and content managers must embrace a new model for developing content, a model that is very different than simply writing a long document in Word and exporting it as a PDF. Some technical competence is required, though the Jorsek DITA CCMS was expressly designed from the beginning to be as user-friendly as possible, without sacrificing capability. Nevertheless, this change can be daunting to authors. In our experience, however, once they embrace it there is no turning back to outdated processes. Again, we work with partners who can assess your specific requirements, design an information architecture to support them, and train your people in its use. If you do not have anyone on staff with DITA or structured content experience, this is the recommended path.

True Collaboration, Finally

So, what is the payoff for this challenging process and is it worth it? First, you gain a tool that offers true collaboration capabilities without the version and ownership issues that have hampered those efforts in the past. This alone will greatly boost the productivity of your documentation teams. Second, many complex manual processes, like formatting for various media formats, become automated, saving enormous amounts of time while speeding up the content development process by an order of magnitude. Other complex tasks, like translation workflow management, are also managed within the CCMS, which can communicate with existing translation systems.

Perhaps the greatest long term payoff of a single source of the truth comes in the distribution potential the model opens up. Mobile, PDF, web, and new emerging models like voice assistants can all be driven by structured content from a central resource. Structured content can be treated like chunks of data, meaning it can be pushed into other business systems with APIs. Jorsek offers an integrated Knowledge Base that provides a mobile-ready HTML portal system, including filtered search, that delivers your content to virtually any device. And there are more benefits that become apparent as you embrace the structured content model.

To understand how a structured content strategy can benefit your business, contact us to set up a brief situation assessment. Our primary goal is to determine whether Jorsek is a good fit for your requirements.

Martin Edic

Martin is a writer and marketer who specializes in creating content for delivery online via the web and mobile. Former Jorsek Employee.
Free 30-Day Trial