Focus on: Structured Authoring

Welcome to the inaugural episode of our Component Content Management System (CCMS) series about the key features of Paligo. Today we delve into the world of structured authoring. In this enlightening interview, we sit down with Roger Gelwicks, an expert in the field, to discuss more about his instructive tutorial, which is found at the start of this interview. Over the course of this series, we will explore the intricacies of using a CCMS, providing you with invaluable insights and practical knowledge. So, without further ado, let’s embark on this journey of mastering structured authoring with Roger as our guide.

Roger Gelwicks: I suppose that’s a good way to start. To be able to explain what structured authoring is, you have to define unstructured authoring. Some examples of unstructured authoring are typing a Word document, or putting together a webpage with HTML. Both of these are unstructured, even though there may still be certain parts of the text that have different jobs. For example, in the Word doc, you may need to adjust the style of a heading or how a paragraph appears. But those types of things could be changed at any time, and all the formatting is done within the same document.

In structured authoring, there are rules for how ‌content is put together. There’s a schema for how to separate the individual parts, or elements, of the document. For example, in DocBook, which is what Paligo uses as its structure, as its schema, there is a toolset involved. If there’s a title for a topic, it has to be at the very top. Paragraph elements cannot be inserted within certain other elements. There are rules for how these elements are supposed to appear together. So structured authoring is basically a way to organize your content around these rules to make it easier to unlock other features, like reuse and versioning.

Roger: When you have structured authoring, it means you have reuse capabilities. For example, if you have a paragraph that you want to reuse, it’s much easier to do that, because it’s categorized as a paragraph element, and every element has its own ‌unique ID. You can easily reuse that ID across multiple documents. So, compare that to a Word document. If you type a paragraph in one Word document, you have to copy and paste it into another separate Word document if you want it to say the same thing, and there’s no link between them. Whereas, in structured authoring, and because everything has an ID, it means that once those rules are in place for multiple documents, and they’re all following the same schema, you‌ have those reuse capabilities.

And versioning is another advantage of that. It’s a similar situation with ‌IDs. Because there is structure, it’s much easier to track as far as revisions are concerned. And that’s what version control is; it’s managing the changes to a document over time. None of that is available if you are working in an unstructured environment. Again, this is compared to a Word document, where the only way you can do that is to manually perform a “save as” function every single time you want to save a revision. There’s otherwise not a native way in Word to do this versioning.

But in structured authoring, you don’t have to do that because it’s tracked as you change the content over time. So those are probably the main advantages. You could also throw translation and localization in there. The ease of translation is also a great advantage to structured authoring because you can easily track the changes to your content over time. If you have a paragraph that reads a certain way, you can also track the translation for that one paragraph. And it’s independent of a translation of another paragraph. So, in the future, if you have a topic and something changes in only one paragraph, there’s no need to go in and re-translate the entire document. We can easily go into the structure and see that this has changed since the last time, but everything else is the same. And that narrows the scope of how much translation needs to be performed, which cuts down on ‌cost. So it’s much more efficient.

Roger: Absolutely. Manufacturing is a great example. Let’s say, for example, you have several products that share some of the same parts. Then, in the next release of those products, a couple of part numbers change. All you would have to do is go in and only change the part numbers in one place, and because those part numbers are reused across products, they’re changed everywhere automatically. That’s much easier to do than to look into every single Word document where those parts are referenced and change them all one-by-one.

We run into this scenario all the time when we’re talking to prospects if they’re not using structured authoring. They have to remember all the different places where they’re using a part number, for example, and update that one part number in every place. It’s a manual effort and it takes forever. But in structured authoring, all of the content is much easier to track. It means you can reuse things more easily.

Sometimes I’ll get the question, “If I change something that’s reused, where is the master that I’m supposed to change?” But it doesn’t work like that. You can change any of the references to it in any location and that’s all you have to do. You change it in one place, and it will change everywhere, because the ID is referenced in every place.
Obviously, the more content you have, the more benefits there are to using structured authoring. You might be able to get by for a long time without being structured because you know where your content is and how it’s formatted. But to really make your content operations more efficient, especially when you’re wanting to separate content from layout, that’s where structured authoring really shines. If you don’t have it and your layout is connected to your content, as in a Word document, if you want to change something, you have to change it everywhere for consistency. In structured authoring, all the content is already done. All you have to do is change what the layout is doing. And then it automatically changes everywhere else.

That also means you can do multi-channel publishing. Once the content is the way that you want it, the content will need to be transformed from the Docbook schema, the XML, into something else, whether that’s a PDF, an HTML5 help center, or even pushing it to a Salesforce or Zendesk article. If you’re not doing structured authoring, all of that content has to exist independently in those places. It’s ‌much easier to simply already have the content the way that you want it and publish to the desired destination accordingly. In the cases where you need content to include or exclude certain elements for different outputs, you can use conditions or profiling. For example, maybe I want the content to look one particular way in a PDF. I can mark a paragraph to appear only for the PDF version, or mark another element to only appear in the HTML5 version.

Roger: In Paligo, you have what’s called a “topic” which is essentially a heading with content under it. That might sound pretty elementary, but if you think about how a document is often structured, if you have a heading with text, that’s the base level of how content is structured. If you’re writing a topic, you’re not necessarily deciding at that point what level of heading that’s going to be. And that’s part of the flexibility you have with structured authoring. Once you’ve framed a topic, you can decide where it belongs in the hierarchy of the document. It could be a level-one topic in one publication but level-two in another, for example.

Admonitions are another great example of how you can divide your content. Notes, cautions, warnings, etc. are often good candidates to be reused. They could, of course, exist independently within a single topic, but often it’s easier if they’re stand-alone components. So you can just drop the component into the topic where you need it. Again, it’s already structured. It’s already the way that you want it. And then if you need to change it, you just go into that one admonition component and change the way it’s worded, and then it changes everywhere else that it’s referenced. Paligo also has another component type called an ‘informal topic’ which is great for cases where you want to reuse a chunk of content, maybe, several paragraphs in a row, without having to manually perform content reuse for one paragraph at a time. Maybe you have a description of something that spans several paragraphs that you’re going to reuse across multiple topics.

Roger: Often with component content management systems, which are structured authoring, there’s a lot to keep track of. Many other CCMSes might be powerful, but not user friendly. However, Paligo puts these two aspects together, with the ability to drag and drop topics in the order you want in the publication structure; how your layouts are going to interact with your content, building a PDF, creating layouts for HTML5 help centers – all of this is easy to do. Paligo makes it really simple and you get the hang of it pretty quickly. A lot of CCMSes have a big learning curve to them. And obviously, if you’re brand new to structured authoring, there’s a learning curve with the concept of it. But once you‌ understand what’s going on, Paligo makes it really easy to make those changes and to understand how your documents are organized.

Roger: With Paligo, we have our schema that we use for our structure called DocBook, which if you haven’t used it before, it is really easy to learn. It’s just another form of XML. So, one of the things that happens in Paligo ‌by default, is that every time you ‌save your topics as you’re working on them, it will validate the content against the DocBook schema, and if there’s a problem, it will tell you that there’s a problem and where to fix it.

That’s another thing with structured authoring. It sounds like there’s rules that might limit what you can do, but what it actually means is that the rules of the schema make sure the content is doing what it’s supposed to do so that the transformations to the different outputs can happen. You would never create a bunch of content in structured authoring and just leave it in XML for the end user. It’s always going to transform into something. So it’s very important that you get the schema correct, because then the transformation can‌ happen without any errors. Paligo does the hard work for you of actually checking the schema as you save. If there are problems, it will point out where they are, and if there are no problems, you get the check mark, which means your content is valid and good to go.

But again, you don’t have to be an expert at DocBook to make use of that. We make it very approachable, and especially if you’re brand new to structured authoring, you really do get the hang of it pretty quickly.

Roger: Multi-channel publishing is a breeze with structured authoring. Because you’ve got your content already structured, it’s just a few clicks to make it into the finished content you want. There’s no copying and pasting. There’s no laborious structure to get things back where they need to go. You have your publication set up and you decide where it needs to go and in what format.

For example, if your content needs to become a PDF, that’s really easy to do. There’s a lot of industries where you can have nicely and meticulously formatted PDFs by the end of your current manual process, but it takes a long time to get there. Whereas using something like Paligo, you’re going to get a really nice, polished, clean and consistently formatted PDF every single time. When the PDF is generating, you don’t have to go into a separate program to format it and make sure that things look the way that you want them to. Once you have the PDF layout set up, it’s much more efficient to generate the PDF whenever there’s a change to something because of how easy it is to update documents. It could take minutes instead of hours or days.

Roger: Using a CCMS like Paligo, instead of a help authoring tool, lets you do more with your content on a much wider scale. You can run into technical limitations if you’re using just a help authoring tool because at the end of the day it’s still unstructured. Maybe there are snippets or equivalents that are able to be reused, and maybe there are multiple output options, but that’s still not the same as an enterprise-level structure that’s‌ being followed consistently.

Roger: That’s part of it. There might still be ways. You could publish a PDF, you could publish a website, but the difference is, it’s still‌ only going off what’s in the topics. And it’s not really following a structure to know where things are going to go. You have to apply styles to get the format the way that you want, so you’re still going to be doing a lot of that formatting in the topic itself. Whereas, in Paligo, all of the formatting is done in a second separate step with the layouts. So there’s a true separation between content and presentation. In help authoring tools, it’s still going to require some manual work to get it the way you want it.

We talk to prospects all the time who realize that they’ve outgrown their current help authoring tool, and Paligo is a perfect next step for them. When you break things down into unformatted topics, all the formatting takes place at a separate step, and it makes your process a lot easier to do.