- 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.
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.
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.
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.
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.
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:
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.