Skip to main content

Topics as structured content

  • Plan availability:
  • Professional
  • Business
  • Enterprise

Topics are the main building blocks of your structured content. You use them as "containers" for each section of your content, and this is known as "topic-based authoring".

Topic-based authoring is different to traditional documentation, where you would write all the content in one long document. With topics, each section is in a separate topic. To create subsections, you can insert one topic inside another topic. The idea is that you write your sections as stand-alone topics, so that they can be reused in many publications.

To create a finished output, such as a user guide, you create a publication and add a collection of topics to it.

The following image shows a publication. Its structure is made up of references to individual topics.

Publication structure. It is made up of a series of topics, which are arranged in a hierarchy, similar to a table of contents in a book.

A "Cybersecurity" publication. Each of its "chapters" and subsections is a separate topic. The topics are added to the publication structure and organized into the appropriate order.

Benefits of topic-based authoring

Why do we use topics? Because they make your content more versatile. You can reuse a topic in many different publications at once, rather than duplicate the information. This means:

  • You can write information once, in one place, and reuse it wherever it is needed.

  • When you update a topic, the changes you make apply wherever that content is reused.

  • Translations are quicker and cheaper. Translation Management Systems (TMS) can identify if a topic has changes that need to be translated.

If you follow best practices and make each topic about one thing, such as one task or one subject, topic-based authoring can also improve the quality of your documentation. By focusing on one thing, you restrict the scope of the information so that the topic is more specific to the user's needs.

Creating a topic and its structure

You can create a topic in Paligo by using the Create Content option and then selecting topic. The Create Content option is available from the dotted menu ( ... ) for folders. Alternatively, you can use the Create Content button at the top of the Content Manager.

When you create a new topic in Paligo, it has a section element, a title element and a para element by default. You can see the structure in the XML tree view side panel. Also, if you select an element in the editor, the Element Structure Menu at the top shows the path to that element.

A close-up view of the top of a topic. Label 1 highlights the element structure menu, which shows the path from the section element to the currently selected element. Label 2 highlights the title of the topic. Label 3 highlights a paragraph.
XML tree view of a new topic. The section element is at the top. Inside that there is a title element that has the title text and an empty para element.

Left image: New topic in the editor. (1) is the Element Structure Menu, (2) is the title, and (3) is a para element. Right image: XML tree view of the topic. It shows the section element is the parent element and it has title and para child elements.

The section element represents the topic as a whole. Within the section element, you need a title as a minimum as defined by the Docbook rules. Paligo also includes a para (paragraph) element to get you started.

For any additional content, you'll need to add the structure first and then enter the content. You can find out more in Elements as structured content.

Example of a topic

Now let's look at an example of a simple topic that you might find in a help center. First, let's see how it looks in the main editor.

Example of a topic. It has a title, a paragraph, a procedure with 4 steps. The third step has text and an image.

Notice that it looks like regular content, with a title, introductory paragraph, and step-by-step instructions. But each part of the content has one or more structural elements to contain the information. You can see them in the XML tree view:

XML tree view of the topic. It has a section element at the top. Inside that it has a title, a para, and a procedure element. Inside the procedure element there is a step element for each step. Inside the steps, there are para elements for the text. The third step also has a mediaobject element for the image.

The structure is made up of a hierarchy of elements:

  • section represents the topic as a whole

  • title is the heading for the topic

  • para is the introductory paragraph and there are also para elements inside each step. The para element is a container for a paragraph or sentence.

  • procedure is the structure for a step-by-step procedural list.

  • step is the structure for each step in the procedure. Note that the step elements are children of the parent procedure element.

    Each step has a para to contain the text for the step.

  • mediaobject is a structure for containing an image. Here, it is a child of the third step, as the image is part of step 3.

This idea of content being inside structural elements is a consistent theme in Paligo. You create a component, such as a topic, to contain the information. You then build the information by creating a structure of elements and adding the content inside the elements.

Note

To learn how to create your own topics, see Create a Topic.