Paligo: Topic or Informal Topic?

Overview: Topics vs Informal Topics

Are you new to Paligo and a little unsure about the difference between topics and informal topics? Then this post is for you.

Here, I'm going to explain:

• The difference between topics and informal topics

• When you should use informal topics instead of regular topics.

Topics in Paligo

Paligo XML uses topics, unlike DocBook 5 XML on which it is based. Each topic is represented by a <section> element and has a <title>, a <para>, and any other content elements you add to it.

When you publish, each topic will be either:

• A top-level page

• A subsection of a top-level page.

For example, let’s say you want an HTML5 help centre page with a main heading and two subsections. For that, you could create:

• A topic for the main heading (the top-level “parent” page)

• A topic for subsection 1

• A topic for subsection 2.

You can then use the publication to “nest” the subsection topics inside the top-level parent topic. Alternatively, you can add the subsection topics into the parent topic by using Insert > Component.

Why don’t you just write the subsections inside the parent topic? Well, you could, but it limits reuse. If you have the subsections as separate topics, it means you can reuse them on their own if needed.

As a general rule, if you are going to write a new page or a subsection for a page, create a new topic.

Informal Topics in Paligo

An informal topic is a container for one or more elements. They are useful because they allow you to reuse a group of elements inside a regular topic. You create the elements in an informal topic and then insert that informal topic into as many regular topics as you need.

If you've ever used MadCap Flare, an informal topic in Paligo is similar to a snippet. Think of them as a container for one or more elements, that you can then reuse in your regular topics.

For example, let’s say you have two paragraphs and an image that you want to reuse in many different topics. You could insert them individually into each topic, but this could be quite time-consuming. A quicker way is to use an informal topic.

1. From the Create dialog, choose informal topic. You then get an informal topic that looks similar to a regular topic except that it has no title. Under the hood it is a little different too, as it uses a <sidebar> element instead of a <section>.

2. Add the content you want to reuse inside the informal topic and save it.

3. Finally, use Insert > Component to add your informal topic inside regular topics, wherever you need the content to appear.

If you need to change the content, make the change in the informal topic. The change will then apply wherever the informal topic is reused.

Some examples of how I’ve used informal topics

I’ve used informal topics quite a lot on Paligo projects. They are especially useful for reusing groups of elements, but can also be handy for reusing single paragraphs too.

“Hold on, isn’t the Reuse text fragment feature for reusing single paragraphs?” Well, yes it is. And it can work well. But when there are many authors using the instance, it becomes tricky to use.

For example, if three writers all create a different “Select Save” fragment, when you come to reuse it, it’s not obvious which one you should choose. It is possible to find out from the fragment’s ID, but it requires a few steps. I’ve found it is quicker and easier to use informal topics and organise them into logical folders instead.

Anyway, I digress! Back to the examples of how I’ve used informal topics:

• Reusing paragraphs that appear in many topics.
  
  The one that springs to mind is a paragraph in the PDF Layout documentation that explains that the settings will take effect when you publish to PDF.

• Reusing several sequential steps in a procedure.
  
  In the informal topic, you need to create a procedure and add the steps inside it. Also, give the procedure element the role attribute and value: reuse-range. You can then insert that informal topic inside a procedure in a regular topic.

• Reusing a paragraph and image.
  
  Sometimes, I’ve needed to use the same image and introductory paragraph or description paragraph in a few places. Exactly what informal topics are designed for.

Summary

Topics

• Use to present sections of content that will appear in your output (PDF, HTML5 Help, etc.)

• Can be added to the publication's structure (the table of contents).

• Use the <section> element.

• Have a title.

• Can contain the elements that make up your content, such as paragraphs and images.

• Can contain informal topics.

• Can contain other topics, admonitions, etc.

Informal Topics

• Use to contain a group of elements that can be reused in many topics.

• Can only be embedded in topics. Cannot be used without topics.

• Use the <sidebar> element.

• Do not have a title.

• Can contain the elements that make up your content, such as paragraphs and images.

• Can contain other informal topics.

• Cannot contain a topic.