Share:
ClickHelp Documentation

Basic Concepts

In this topic, we 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 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. This means that you can work on a new version of a user manual without affecting the current version of it.

  • Project Template 
    When creating a new project, you can select any of the predefined project templates to get ready design. Styles, images, backgrounds, and colors are  parts of every project template. All templates have a number of sample help topics that demonstrate the design of the main elements to help you get started. Upon project creation, you can modify the 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 the, accessible only to Power Readers upong 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 organizaed in some logic structure. Those small documents are called topics. Every topic has its title and the contents. Topics are organized in a tree-like navigation structure that is shown in the Contents panel - this panel is used by readers to navigate among topics.

  • TOC (Table of Contents) 
    The table of contents is a logically-organized tree-like struture 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 the content of one help topic to another topic's body. The element that you insert to 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 that are used in many places across a user manual, and may have to 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 the variable 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 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. In that CSS file, you will find all styles that define the template you selected - colors, backgrounds, customer bullets for lists, etc. So, you can easiy 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, which makes 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. When publishing a project, ClickHelp will process all conditional blocks to either include or exclude them from the content.

  • Export Configuration
    ClickHelp supports exporting the published manuals to offline documentation formats like PDF, DOCX, ePub, etc. During the exporting process, users can specify a number of parameters that affect the final output - page numbering, heading styles, etc. To avoid having you to specify the export parameters every time, ClickHeklp 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.