Topic-Based Authoring
ClickHelp is a topic-based documentation system. The topic-based approach is more efficient for producing and managing documentation, as compared to the book-oriented approach. In this topic, we'll tell you about the basic principles.
Topics
In order to make your documentation more effective and user-friendly, you should create a topic for each section or each task your readers are looking for. Take a look at the example below. As you can see, there are two sections with headings. Whenever it's possible and makes sense, it's better to turn them into separate topics, especially when each section is pretty long.
Why should you do this? Writing content in the form of topics as opposed to creating a single long document has many benefits - it will be easier to:
- Translate. In ClickHelp, you can create a multi-language user manual. To learn more, refer to this topic: Create Multi-Language Documentation.
- Reuse. For example, you need to reuse a topic in different places of your TOC, there is no need to copy and paste the content. To learn more, refer to this topic: Reusing Topic in Multiple ToC Nodes.
- Update. In ClickHelp, you don't need to republish the whole project if you need to update a few topics that were re-written or improved. You can use the Partial Update publishing mode for this purpose. So, you can push the latest content to some of the topics, without changing those topics that are not ready yet. To learn more, refer to this topic: The Partial Update Publishing Mode.
- Collaborate. Each topic has its own Assignee, Status, and Owner, so different topics of the same project can be assigned to different people, can be reviewed separately, and you can see the changes history for every individual topic.
Publications
A publication is a collection of topics. Here is what online documentation looks like:
The publication structure looks like a table of contents, and it has various sections that are separate topics. This is more convenient for users because they can find necessary information quickly since they don't have to scroll down the wall of text.