March 30, 2023

Structured content authoring for complex documentation

Share
image shows different versions of cars

Whether your field is hardware, software, finance, insurance, medical technology, or almost any type of industry, there is one common challenge: managing complex and multidimensional documentation.

In this article, we’ll make a case for structured content authoring and autonomy, rather than the file-based system. We’ll also talk about the complexity of documentation, as well as enterprise silos and how to break them down.

Using structured authoring to keep track of your product documentation

The problem is that documents exist across multiple variants, which can make it difficult to keep track of everything. Projects may have multiple versions of a product that must be documented, or multiple output formats. Not to mention, documentation targeted toward various types of audiences. There are even more dimensions, such as operating systems or languages, that must be considered when documenting a project.

For example, a car company has many different models of cars. These cars share many similarities, like four wheels, a gear shift, and a steering wheel. But even within the same model there are some key differences in versions and variations. The Standard model may have very different looking variations – car manufacturers often produce both Estate and Sports variations of a Standard model – and even in that same Standard model, there might be different equipment versions: for example a Standard feature version, an Eco version and a Luxury version.

The Standard, Eco and Luxury equipment versions all have a rear spoiler. The same rear spoiler is shared with all the Sports equipment versions. None of the other models, except for these, have the rear spoiler. Therefore, we’ll make a component called “rear spoiler.”

Because these two models share this rear spoiler, or component, the documentation also needs to reflect that. There must be a topic, or a chapter, or section that explains the functionalities of the rear spoiler, which is tracked and shared in the respective versions and variations documentation.

Managing variations in structured content authoring

Another example of a variation in documentation would be the audience to which the information is directed. In the case of the aforementioned car company, manuals must exist with a focus toward different audiences. First, there is the service manual. Second is the owner’s manual, which is typically printed and stored in the glove compartment of your car. And finally, you have the repair manual or the mechanic’s guide.

There is a bit of a difference between the owner’s manual and the mechanic’s guide. The structured content that is provided to the mechanics exceeds the knowledge that the user needs, because mechanics have the knowledge, ability, and skills to repair the car. Basically, it’s more technical information. With more technical information, there are additional components.

If we take away the car analogy and replace it with software or a service, there are other situations contributing to the complexity of multiple operating systems. To illustrate this, any software application, such as an ecommerce application or banking app, will have something that is specific to one particular operating system. The way the Facebook app behaves on Android is different from how it behaves on ‌iOS. Although it is mostly similar, there are some differences.

Localization of your documentation

It’s important to keep in mind that if you’re delivering a software product, there is an added level of complexity provided by the operating system, which isn’t necessarily something a car company would need to consider.

Going back to the car company analogy, we can also look at languages. A large car company will make cars that are used in many countries around the world. Depending on the size of the company, you may have users in over 100 countries. And many of these countries speak different languages. This company would need to make sure that a customer in Japan could read their manual in Japanese. Or that a customer in France could have a French mechanic’s guide.

There is a need among almost all industries to localize, and content should be available in the user’s native language. However, just having the correct language isn’t enough. Each country may have different regulations as well.

For example, in the EU, there are 24 different official languages, but only one common market, with shared rules and regulations. So if a company wants to sell cars in Europe, there is one uniform law and legislation that must be adhered to, regardless of the language in which the documentation is written.

Single source authoring

At the same time, when focusing on countries like Australia, South Africa, the United Kingdom, and the United States, the language is always English. But there are always minor differences. In British English, the metal cover over the car engine is called the “bonnet”, while in American English it’s called the “hood.” Of course, this isn’t the main issue. The main issue is that each of these four countries share the same language, but have very different regulations.

We can see the same issue with South America. Except for Brazil, the common language is Spanish. It’s slightly different from the Spanish spoken in Spain, but the main point is that there are different regulations.

Structured authoring is a huge time saver

Let’s take a look at just how complex the content can become for this car company. Let’s assume this company has 50 car models. Each of the cars has five versions per model. That’s 250 different pieces of documentation that must be produced, and 3 manuals for each. Now the number of documents is up to 750, and they all need to be translated across 20 different languages, bringing the amount of documents up to 15,000.

So we take a topic, like tires, that is common to all 15,000 different documents. This company decides to change their brand of tires for a more cost-efficient brand that offers better performance. Without structured authoring in a Component Content Management System (CCMS), the company’s technical writers would have to spend weeks or even several months to complete the job.

Obviously, a file-based system isn’t efficient for this level of content, because no one wants the task of opening 15,000 documents. Large companies dealing with multiple variations of content must have an efficient system, which is why a single-source, CCMS is the obvious choice for most enterprises.

XML-based structured authoring

If you need to produce complex multidimensional documentation, use a different approach. Don’t do it with a file-based system or unstructured authoring. Unstructured authoring is a proprietary format. It’s mostly file-based. It also contains a lot of inconsistencies and idiosyncrasies.

The approach that we want to follow is XML-based structured authoring in a CCMS. And with that comes a different paradigm because we’re not working with a file-based system.

Typically, if you use a typical file-based authoring tool, you’re saving your files to your own computer, which means you won’t be able to do extensive content reuse. Whereas, with a single-source database, it’s a different paradigm. The content is available for everyone to reuse. Most importantly, when a single component, like tires, must be updated in 15,000 documents, it’s very easy. You only need to change the source, and the updates will propagate everywhere that component is being reused.

Summing up the benefits of structured content authoring

As we’ve shown, enterprise companies benefit the most from using a structured authoring approach because there is always complex multidimensional documentation, regardless of industry. It’s important to consider authoring, updating and content reuse, when managing complex multidimensional content. With an XML-based structured authoring approach, you can update your content more efficiently, fix all the idiosyncrasies, and publish in multiple different output formats.

If you are interested in learning more about structured authoring for complex multidimensional documentation, I’ve recorded a tutorial here.

You can also read more about how our customers benefit from the Paligo CCMS with technical documentation and product knowledge management in our customer case studies.

Share