Share:
ClickHelp Documentation

Basic Concepts

This topic will cover the main ClickHelp notions and how they are related to each other.

Documentation Portal

This notion refers to the entire web application you are getting when using ClickHelp.

Every documentation portal has a unique address of this kind: portal-name.clickhelp.co.

Your documentation portal is a single place for your technical writers to work on the content and for your clients to read user manuals. Thanks to the ClickHelp architecture, authors can create new content without affecting what readers can see.

Project

You create a new project to start developing a new user manual. All help topics you create are stored in the project. Projects are used only for documentation development, not for giving access to readers. Projects are visible only to the authenticated users after logging in to the documentation portal.

Project Template

When creating a new project, you can select any predefined project template to get ready design. Styles, images, backgrounds, and colors are parts of every project template. All templates have several sample help topics that demonstrate the design of the main elements to help you get started. Upon project creation, you can modify all design elements by editing the project CSS file that was auto-created based on the template design.

Publication

When a documentation project development is completed, you publish the project to produce an online user manual. The publishing process creates a publication. Every publication of a project is shown as a child element of the project on the Projects page. One project can have multiple publications. Publications will be visible to the readers when they open your documentation portal home page. You can also hide certain publications or make them accessible only to Power Readers upon logging in - this is controlled by the Visibility property of a publication. During the publishing process, ClickHelp will handle all dynamic elements and generate them in the final form: variables, snippets, conditional blocks - all of them will be expanded to simple HTML content.

Topic

The topic-based authoring approach assumes that a user manual is not one long document but a set of smaller documents organized logically. Those small documents are called topics. Every topic has its title and contents. Topics are organized in a tree-like navigation structure shown in the Contents panel - readers use this panel to navigate among topics.

Translation/Localization-Related Notions

With the addition of the Translation module, a whole new layer of new notions was added to ClickHelp. You can read more about translation/localization-related terminology here: Creating Multi-version Manual: Localization Terms.

TOC (Table of Contents)

The table of contents is a logically organized tree-like structure of topics. TOC nodes may have help topics associated with them (they show up when you click the node), or they may be folders without a separate help topic associated with them (when you click a TOC folder, no topic navigation happens).

Snippet

To implement content re-use, you can include one help topic content in another topic's body. The element that you insert into the target topic body is called a snippet. Snippets refer to the source topic by URL and pull in the entire source topic HTML content to show it in the target topic. Snippets are often used to implement repeatable parts of topics, like headers or footers.

Variable

Variables are plain-text string values that have a unique name inside a project. They are used to store the values used in many places across a user manual and be updated in a centralized manner. A good example is the version of a software product. If you mention the version number in the documentation, put it to a variable and insert it whenever needed. When you have to modify the version number, you change the variable value rather than changing every topic where it is mentioned.

Conditional Block

You can make some part of a help topic contents conditional. This means that this part may or may not be included in a publication depending on the Publish Configuration selected during publishing. For every conditional block, you can specify which publish configurations it should be included to or excluded from. The most common scenarios of conditional blocks usage are: removing the topic footers when publishing for later PDF export, replacing videos with their URLs for printed output, etc.

File Storage

When creating online documentation, it is often needed to include a screenshot, sample files, etc. To use those files in your ClickHelp documentation, upload them to the ClickHelp File Storage. You can insert images from the storage to help topics and give download links to sample files located in the storage.

Styles

While editing topic contents, you can use various styles for the text content - make it bold/underline/ italic, change the font size and color, etc. In addition to those inline styling options, ClickHelp supports advanced styling of online documentation by using CSS. In the settings of a project, you can see the list of CSS files of this project. These CSS files will be loaded when viewing any help topic from this project. When you create a project from a template, you get a ready CSS file included in this project. You will find all styles that define the template you selected in that CSS file - colors, backgrounds, customer bullets for lists, etc. So, you can easily modify the look of your online documentation project by changing the styles defined in the CSS file. Projects and publications can share CSS files, as well as have their own unique files.

Scripts

Scripting is an advanced concept, making it possible to implement any dynamic behavior of your online documentation. Every project may have several script files (*.js) included - you can see the list in project settings. Those script files will be loaded every time a help topic opens. You may want to add script files to your online help to use a ready syntax highlighter for code examples or give readers a way to interact with the content in some way.

Output Tag

Output tags are named configurations used for dynamic output - content elements (text blocks, TOC nodes, styles files) may be included or excluded based on their output tag settings and the output tag specified in the publishing wizard. ClickHelp will process all conditional blocks when publishing a project to either include or exclude them from the content.

Export Configuration

ClickHelp supports exporting manuals to offline documentation formats like PDF, DOCX, ePub, etc. During the exporting process, users can specify the number of parameters that affect the final output - page numbering, heading styles, etc. To avoid having you specify the export parameters every time, ClickHelp allows creating an Export Configuration that captures all parameters for future use. Export configurations are stored inside the publications for which the configurations were created. Export configurations can be managed via publication settings.