Topic-Based Authoring

Abstract

Paligo is designed for "topic-based authoring", which is a more efficient way of producing and managing documentation. If you are new to topic-based authoring, this section explains the basic principles.

Paligo is designed for "topic-based authoring", which is a more efficient way of producing and managing documentation. If you are new to topic-based authoring, this section explains the basic principles.

Topics

With topic-based authoring, you create each section of your content in separate "containers" called topics. So instead of creating your entire document in one place, as you would in a Microsoft Word file, you create lots of separate topics. As a general rule, you should create a topic for each section of your content that needs a heading. For example, the following page has two sections with headings, so to create that content in Paligo, you could add one topic for section 1 and another topic for section 2.

Topics-based Authoring - example

Writing content in topics has many benefits. They are easier to manage and translate, and you can reuse them in different publications. This can significantly reduce the cost of updating your content, as when you change a topic, the changes apply wherever that topic is used.

Note

If you have each section and sub-section as separate topics, they are easier to reuse in different contexts. But there are ways to add sections and sub-sections in the same topic. To find out more see Headings and Subheadings.

Publications

A Publication represents a collection of topics that you want to publish as an output, such as an HTML5 help center. Think of them as a table of contents, where you choose what topics to include and what order to present them in.

The following image shows a publication for a "Mars Travel Manual". You can see that the publication's structure looks like a table of contents and it has various sections. Each of those sections is a separate topic (so there is a topic for "About Space Travel", a topic for "Space Safety", a topic for "The Mission Control Center" and so on).

Topic-based authoring structure

A publication called "Mars Travel Manual" which contains many topics, including "About Space Travel", "Space Safety", and "The Mission Control Center".

You can add a topic to more than one publication. This is one of the main benefits of topic-based authoring, as it means you can write a topic once, and then use that same topic in many publications.

Topics in three publications

A topic can be added to many publications.

You can also publish part of a publication rather than the entire publication. This is useful if you have sections of a publication that could work as a separate output.

To learn how to create publications and topics, see: Topics and Publications.