Make technical documentation smart - from content management to content delivery

Corresponding services: Smart content and iiRDS and Self-service applications

In this article, Martin Kreutzer and Ulrike Parson describe how you fill content delivery portals with smart content so that users quickly get the right answers to their questions.

Smart content (aka intelligent information)

With digital transformation progressing, printed documentation is increasingly being replaced by smart content that is available online. But what exactly is smart content? How can content be smart anyway?

That’s right, content itself cannot be smart. The term “smart content” describes content that can be processed by smart applications.

Characteristics of smart content include:

• It is modular.
• It is created format-independent and, as a consequence, can be displayed on different end devices.
• It is enriched with metadata and thus facilitates semantic search and context-sensitive processing for different target audiences or application scenarios.

We encounter smart content in marketing, wikis, on websites, and also in technical documentation. But what exactly are the consequences of making content smart for technical documentation?

Smart content in technical communication

Users always search for content within a specific context. The context is usually determined by the product that is used and the task at hand as well as the role of the user. If these aspects are established, the relevant information for a certain question can be searched.

It is, however, not enough to flag complete documents with context categories. Contextual information becomes more valuable when documentation is available in modules – or topics. A topic is a piece of information that answers one specific question. Examples are:

• How do I configure my cell phone for first use?
• How does Bluetooth work?
• Which Bluetooth standards does my phone support?
• My Bluetooth connection does not work. What do I?

The examples demonstrate the different types of topics that exist tasks (instructive), concept (descriptive), reference (looking up) and troubleshooting.

If a solution description is available as smart content, users can find the description in a large documentation pool by entering only a few pieces of contextual information. Example: The user has a problem with the Bluetooth connection of the cell phone. The user can narrow down the search by specifying the product (model of the cell phone), the component or function (“Bluetooth”), and the topic type “troubleshooting”.  Usually, there will be only one topic available for this combination of search criteria.

Making documentation smart means to organize content in topics and assign useful metadata to it.

Smart content makes technical documentation an asset

Can smart content increase the value of technical documentation? Absolutely! Manufacturers deliver documentation with each of their products. Often, this is printed documentation or PDF files, their digital equivalents.

Usually, there is not much interest in these documents. Companies don’t recognize the business value of the information contained in these documents, and customers try to avoid reading them altogether. Rather, customers expect a great service experience whenever they have a question or problem. Consequently, technical documentation is seen as a necessary evil, which exists for legal reasons only.

If you see through the eyes of users and manufacturers at the same time, both views are actually two sides of the same coin: If the manufacturer provides smart content to users, the content adds value to the product that the users have bought. This is because the users save time and money looking for information. On the other side, manufacturers can strengthen their market position. As products of competitors become more interchangeable, manufacturers can strengthen their position by providing better service – with the help of smart content.

Generating smart content from technical documentation and publishing this content on the company website or information portals, possibly combined with marketing information, increases the content’s visibility and reach because technical documentation usually contains the most important keywords that users use in internet searches. That means that smart content opens new possibilities for companies to distinguish themselves from their competitors and increase their visibility.

Linking information across manufacturers

However, publishing information on your own portal only is not enough. For complex plants or web applications, content must be gathered and aggregated from different sources and manufacturers. To be able to process this content in a common way, it must be enriched with the same categories of metadata – meaning that the metadata follows the same semantic model. Otherwise, the content delivery portal (or any other application) becomes too overpopulated with information, searches generate wrong results, and the actual value of the information is lost.

In conclusion, we need standards to make smart content interchangeable across systems and manufacturers.

iiRDS: a new standard for the delivery of technical documentation

The German Association for Technical Communication (tekom Deutschland e. V.)  identified this need for a standard in 2016 and created a working group with the goal of developing an exchange standard for intelligent information. The result of these activities is „The Intelligent Information Request and Delivery Standard“ (short „iiRDS“). Version 1.0 of the standard will be published just in time for the tekom spring conference in 2018, and the development of the standard will be handed over to the newly founded iiRDS Consortium. 25 companies and institutions have become a member of this consortium so far.

iiRDS defines a common vocabulary for metadata of technical documentation content and a package format for delivering content including its metadata. The vocabulary defines metadata that makes technical documentation content smart and it also defines the possible relations between the metadata classes. The package format enables the exchange of content across manufacturers and systems.

The iiRDS metadata model

In the heart of iiRDS, there is the information unit. It represents the metadata that is used to classify a content module. Metadata may be defined for content modules of different sizes: documents, topics, and fragments. Fragments are parts of a larger unit, for example, the tools that are needed for a step in a repair instruction.

In iiRDS, metadata is categorized into different classes, for example information type and product metadata. The information type metadata describe the kind of information. Product metadata defines the product or component to which the information unit applies.

The example of the Bluetooth problem illustrates the classification of a topic about Bluetooth troubleshooting.

Complex devices need further classification: For example, information about the product lifecycle phase may become relevant:

• Information subjects include general warnings messages, technical data, declaration of conformity.
• Product lifecycle phases include assembly, configuration, operation, close-down, or disposal.

Two further topics illustrate how to apply the metadata.

In addition to the metadata described above, iiRDS offers functional and administrative metadata. We will not explain this metadata in detail here.

The more complex documentation gets, the more important it is to classify information with metadata. iiRDS, however, does not require that you fill all the metadata contained in the standard. Ever company can fill the array of metadata that is most relevant to the user scenarios of their customers.

A common vocabulary for technical documentation

iiRDS predefines language-neutral terms and value lists (taxonomies) for the domain of technical documentation. This ensures that terms and values always have the same meaning across manufacturers and systems. Let us use the “operating instructions” as an example:

Operating instructions (or “Betriebsanleitung” in German) are a type of document. iiRDS does not only contain the definition of this document type but also the English term. A document that is classified as „Betriebsanleitung“ is linked to the IRI (Internationalized Ressource Identifier) and receives predefined semantics for operating instructions.

iiRDS also offers predefined values lists for information types and product lifecycle phases.

iiRDS does not offer predefined value lists for products and components because these differ from manufacturer to manufacturer. Therefore, manufacturers maintain their own classifications (taxonomies) for products and components. In the metadata, they use their own IRIs for product and component metadata.

From content management to content delivery

A lot of technical documentation content is created and maintained in a component content management system (CCMS). Technical communicators use these systems to create text, to manage modules and assign metadata, and to manage their workflows.

If a CCMS supports the iiRDS metadata scheme, technical communicators can use the iiRDS taxonomy to classify documentation modules. This creates the basis for delivering technical documentation content to content delivery platforms via iiRDS. Standardization ensures that data can be aggregated from different management and authoring systems and delivered to different content delivery platforms.

Currently, several manufacturers are working on implementing iiRDS in their systems. For the tekom annual conference in 2017, Empolis created a prototype of the import interface for the information management system Empolis Content Express. A productive version of the implementation is on the roadmap.

Related articles

• Mark Schubert: RDF is not XML - RDF serialization and iiRDS metadata
• iiRDS - a standard for intelligent content