Tutorial: Complex Documentation Using Structured Authoring Principles

Hello folks and welcome to structured authoring to manage complex multidimensional documentation. My name is Andrea and these were the slides that I presented at the CCMS Open Forum in Bologna in late 2022.

The topic is general enough and I think it could be useful because at times when we start with a little one-on-one, we’re missing the big picture. So this is what I’m here to do today.

I’m going to provide a big picture for Paligo. I’m going to make a case for structured authoring.

I’m gonna make a case for a database versus the file pay system and we’re going to talk about the complexity of the documentation as well as the enterprise silos and how to defeat them.

First of all, as of this video recording, we do business with about 600 enterprise customers. They come from hardware, they come from software, they come from banking and insurance, med tech, all sorts of industries and businesses. They all have one common challenge.

The challenge that they’re trying to fix is managing the complexity and the multi-dimensionality of the documentation of instructions, of content. So what is it?

The problem is that documents exist in many variants. Okay, so we have products down here. Every project might have multiple versions of that product that need to be documented as well as audiences or output formats.

Now there are more dimensions, operating system, languages, but you know, I just want to keep this first slide very high level so that you understand a little bit.

And now I would like to make a quick example to explain that complexity.

This is Toyota. Toyota has a Prius Corolla and 48 other car models. Okay, my personal favorite is probably the Rav4. But the point is that a lot of these cars look similar, right?

They are similar, they all have a steering wheel, they all have a shift stick. They all have four wheels, but there are also some key differences. The Land Cruiser product looks extremely different from the I.Q or from the SAI. Now, within the same model we might have different versions. So we have the standard feature, then we have the LE , the LE Echo and so forth.

Now note that the 50th Anniversary Special Edition has this little rear spoiler which is a component. That is shared with another version right here. The XSC. None of the other models have the rear spoiler.

But these first two, the two versions, the Ecstasy and the 50th Anniversary Special Edition, they do share this particular piece, which means that the documentation also needs to reflect that. There needs to be a topic or a chapter or a section that explains the functionalities of the rear spoiler.

For example, we also have audiences, and this image illustrates a very wide range of audiences, but for the car and for Toyota we’re just gonna talk about three different audiences.

First is the dealer manual. The second one is the user manual, which is typically printed and sorted in the glove compartment of your car. And finally you have the maintenance manual or the mechanics guide.

And now there is a little bit of a difference between, for example, the user guide and the information, the structural content. That is provided to the mechanics because the mechanics have the knowledge, the skills and the ability to go and repair the car, that far exceeds the knowledge that the user needs. They’re more technical in other words.

And so the mechanic’s manual needs to have additional different components. In other use cases when we’re creating a software product or service, we need to deal with the complexity of multiple operating systems.

If I’m Facebook or if I’m Google, whatever software application, obviously I’m going to have something that is specific to one particular operating system because the way you do, the way the Facebook app behaves on Android and IOS, it’s similar yet different. And, it might be different if they choose to create a desktop for Linux or Symbian or Windows.

So we need to keep in mind that if you’re delivering a software product, there is that added level of complexity provided by the operating system, which is not necessarily something that Toyota will need to take into account.

But I just thought I’d mention it because it’s important. Then we have languages, you have users in 250-300 different countries. They speak all sorts of different languages. And we need to make sure that if a Toyota user is in Japan, right, I’d rather read the manual in Japanese. Not everyone in Japan is able to read English, for example, and so on and so forth.

So we need to localize and we need to make sure that the content is available in the native language of the users. The concept of country, it’s a different concept from language, obviously.

Let me give you a couple of examples. In the EU, we have 27 different official languages, but we have one common market, and shared rules and regulations. So if you want to sell cars to Europe, there is one uniform law and legislation you need to abide by.

On the other hand, when we look at countries like South Africa, Australia, the United States, the U.K., the language is always the same. It’s always English. Yes, there are some minor differences. You know, we call a lift, elevator, in British and American English, but that’s not the point. The point is that each of these four countries, UK, South Africa, Australia and the U.S. have different regulations.

Okay, so there are entire chapters in the Toyota user guide, or dealer guide, which needs to be tailored specifically to the laws and regulations of this country’s safety and security. And so, once again, there is the language element aspect of this, but also there are some conditions that specifically apply to countries that speak the same language.

Okay, same goes with South America, where, with the exception of Brazil, they speak Portuguese, they all speak Spanish. Yes, it’s slightly different from the Spanish from mainland Spain, but there are different regulations. We’re talking about a lot of different countries.

So if we continue with the Toyota analogy, let’s have a look at how complex content can become for them. We’re keeping this very simple. We’re making some assumptions.

Okay, they probably have more than 50 car models, but we’re saying that they have 50 cars. Each of the cars has five versions per model. That’s 250 different pieces of documentation that need to be produced three times. Again, very conservative.

If we go by that assumption, we have 750 documents, 20 languages, which once again is very conservative, but you know, that will set us on 15,000 different documents.

Now, consider this. There is a topic, the tires. That is common to all of the 15,000 different documents. And if Toyota decides one day to change the entire provider from Bridgestone to Michelin, what are they gonna do? Are they gonna open 15,000 different documents? The answer clearly is no, because that would be foolish. Monkey business.

That could take you anywhere between several weeks to several months to complete, depending on how many people work on it. So that’s not the right way to do it.

So if you need to change components, shared across 15,000 different documents, you will be better off with single sourcing and you’d be better off with the database. Why? Because the file-based system is not efficient. It doesn’t fit for that purpose. You’re not going to open 15,000 different documents, you know?

And if you are working within structured authoring, with a file-based system, then you’re building this house of cards that is starting to crumble at the first adversity. So don’t do that.

If you need to produce complex multidimensional documentation, use a different approach. Don’t don’t do it with a file based system and don’t do it with unstructured authoring either.

So, structured authoring, as we will see in one of the future courses, it’s a proprietary format.

It’s mostly file based. Not always, but it’s mostly file-based, and it contains a lot of inconsistencies and idiosyncrasies that we don’t like very much.

The approach that we want to follow, it’s an XML-based approach of a structured authoring CCMS. And with that comes a different paradigm because we’re not working with the file based system. So, FrameMaker, AuthorIt, sorry, FrameMaker, Robohelp, MadcapFlare. They use a file based system.

So if you’re a Flare user, you’re saving your file on your own desktop.And you’re not gonna be able to do extensive content reuse as well. Whereas, with the database, right? It’s a different paradigm. The content is available for everyone to reuse. And most importantly, when you need to fix that single component, like tires, that needs to be updated in 15,000 documents. It’s super easy. You only need to change the source and the updates will propagate everywhere that component is being reused.

This brings me to another important concept, right? We don’t work with monolithic documents anymore. Okay, It’s not a word document with different headings and different chapters. We’re doing topic based authoring, which means that the publications are put together by using and reusing different topics.

Now within the 50 car models, Toyota is producing some of the topics that are unique for sure. Because different cars and different models within that product family, within the Corolla family, or the previous family, are unique to the Corolla and are unique to the previous. But there are a lot of topics that can be reused and are reused in different nesting of the documents in different levels.

Okay, so, to continue with that analogy, for example, tires will be reused in all of the pieces of documentation. And it’s reused as is, which makes it easier to update when we switch from Bridgestone to Michelin. And that concludes the first part of the presentation.

The second part is to tackle another problem, which is the problem of enterprise silos. And the inspiration from this part is coming from LavaCon 2022, where I participated in an interesting presentation by this lady down here. Her name is Sarah O’keefe. She is a guru in the content management industry and this is the castle that inspired the World Disney Global.

Okay, it’s somewhere somewhere in Germany, I’m not gonna attempt to pronounce it because it’s really difficult, but that’s the Disney Castle guys, ladies and gentlemen, folks. So one of the things that you will understand by looking at this picture is that all of this is complex, as much as it’s beautiful, it’s very diverse.

Because the pieces, the different buildings here were built by different architects in different periods of times and that’s a really good analogy when it comes to the content enterprise companies put online. Because you know, this big building, this main building represents the main website, it’s typically owned and maintained and updated by marketing. But then there are other content types that are published to the web that have slightly different styles. They shouldn’t, but they have knowledge based on their training in the LMS, Doc, and finally the developers community out there.

I found the slides hilarious because this happens every time with every company, you know, and it’s a real challenge, a challenge that is structured authoring an XML based CMS is capable of solving.

And so you have pubs, technical documentation, here and then you have support documentation and learning and development content as well as a PI and technical documentation, technical software documentation in the best case scenario.

In the worst case scenario story, there are four different teams that are authoring content that is supposed to be similar but it’s not. And in the best case scenario there is some sort of copy pasting or we’re saying similar things.

In the ideal scenario you have a CCMS that allows you to reuse and repurpose the same content in a very fast way into multiple output formats and liquids such as CCMS, among others as well, to achieve the level of reusability and multi-channel publishing, you need to separate the content from the layout.

You want to make sure that you have content broken down in chapters and sections in topics and that you can put them together. And in another place you can work on the layout, which might be different. You know, your pdf layout might be different from your html layout or scoring layout. Also the concept of white labeling. You can produce virtually an unlimited amount of layouts that you can pair with the content.

So if you’re a customer, if you’re a company that has multiple brands that they need to manage, but the content is pretty much the same, then you can definitely work on separate layouts.

So in conclusion, structural authoring is the way to go. And it’s important that you have all of the above under a unique roof, a unique platform where you can author, reuse versions, the content, collaborate, translate and publish to multiple channels.

But today, really the focus was on authoring the content, updating the content and content reuse because it can be quite challenging to manage complex multidimensional content in an unstructured way.

So the way to go here, it’s the structured XML approach that allows you to more quickly update the content, fix all of the using processes and publish to 10 or 15 different output formats to make sure that not only is our content beautiful, just like the Disney Channel, but it’s also cohesive and coherent. And that we’re using the same words and the same styles, you know, even if we’re publishing the content in three or four or five different output formats, because that’s how the customers want to consume it.

So now you see why large enterprise companies prefer to use a structured approach, regardless of the industries that are in the minimum common denominator. They always have complex multidimensional documentation.

Thank you and see you on the next one.