The federated Help authoring system

The federated database is a term that has been growing in popularity in recent months. According to Wikipedia:

Through data abstraction, federated database systems can provide a uniform user interface, enabling users and clients to store and retrieve data in multiple noncontiguous databases

Could a similar approach be used in the field of technical authoring – could we have federated Help authoring systems?

There’s a number of situations where a federated Help authoring system might be needed:

  1. A company is selling a system that includes products from other organisations. For example, a telephony solution might include handsets supplied from a third-party manufacturer. This systems integrator is likely to want the handset manuals to use their product name, “look and feel”, contact details and company logo.
  2. Another subsidiary or department is creating documentation in their own Help authoring system, and you need to include some of their content in your user documentation. For example, these could be Knowledge Base articles created by the Support department, or embedded Help written into the application screens by the programmers. They cannot or do not want to use the same authoring system as you, and you don’t have the authority or desire to enforce your system on them.

There are a number of ways a federated Help authoring system can be set up:

  • One is to agree a common data structure. You could require your suppliers to make their user guides accessible in DITA format (instead of, for example, InDesign). You would need to define which text you wanted to be conditional – such as the company name, product name and contact details. In a federated model, their content would stay in their system, but could be integrated with your content when you generate the user documents. This means if they updated the manual, these changes would appear in your system.
  • Another approach is to simply have the content as an embedded object in your authoring system. You would need to get your colleagues to create content where the formatting information was not embedded with the content itself, and again you’d need to agree which text you wanted to be conditional.

The attraction of this approach is it minimises the effort required by the other writing teams, and it provides a solution where you don’t have the ability to establish a single authoring solution.

If you’re doing this today, feel free to share your experience.

One Comment

Mark Baker

I believe federated databases should actually become the default approach for tech comm and content strategy. The idea that you need to keep everything in a single repository is very 20th century. Structure locally; exchange globally.

But the way you make this work is not to force every repository to use the same format. A large part of the virtue of the federated database approach is that it lets each group optimize its database structures for its own purposes. This is lost if you force everyone to use the same structures. Common formats are less semantically rich than specialized ones, and that loss of semantic richness is the very reason you don’t want to force all content into a common format.

What you need for federation to work is not common structures, but semantic equivalence — the ability to translate one structure into another. This preserves the ability of local systems to optimize for local concerns while also enabling everyone in the enterprise to federate content when they need to.

To get semantic equivalence, you need to establish a minimum exchange standard that all systems must meet. Each system can then develop its own structures how it likes as long as it maintains the capability to transform into the exchange standard.

The local standards will, naturally, be semantically richer than the exchange standard, so some external users may want access to the local standard as well. Thus each local system should provide:

* Access to its data in its internal format.
* A description of the internal format.
* Access to a feed of its data in the exchange format (or formats).

For example, a documentation system might provide a feed of data in its own custom XML format as well as feeds of the same content down-translated to DITA and DocBook.

This approach give you the ability to optimize local processes while preserving the ability to exchange content across the enterprise.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.