ClickHelp User Manual

Release Notes: March 2019 — Aurora Polaris

In the Aurora Polaris update, we improve the topics review functions, the Table of Contents panel, the whole publishing process, and much more. You will see several new reports and 30+ topic metrics, including readability metrics. You will also experience better performance, improved UX, and easier topic publishing flow. Keep reading to learn all the details.

New Features

Breaking Changes

Branding CSS is now applied to topic content in Web Help. If you have some CSS classes appearing both in the portal Home page and in help topics, make sure their CSS selectors in Branding.css are unique and home page styles will not interfere with your help topics. The same applies to CSS rules affecting all tags having specific names or attributes - now, they will be applied to your topic content as well. No changes needed for project styles - they are still applied to your topic content only.
Your project scripts may now affect the Web Help navigation UI since they are now loaded into it. If you're publishing to the Web Help format and have some logic in your project scripts making changes to all tags having specific name (e.g. all links) or working with the page body, you may want to check how the logic will work for you now in newly exported Web Help manuals.
Automatic notifications from ClickHelp are now sent from info@clickhelp.com (was info@clickhelp.co previously). If you have some filters, whitelists, firewall rules configured, you will need to update them with the new email address.

Topic Editor

Reusing topics via creating multiple TOC nodes for them in a single project or in different projects became even easier with the new "Reuse" mode which can now be selected when creating a new topic in TOC.
It is now possible to copy topics (including cross-project copy). When copying a topic from one project to another one, source project images used in the topic are copied to the target project automatically if needed (it's possible to select whether they'll overwrite files in the target project).
Thanks to the Copy Topic feature, it is now possible to have multiple topic templates defined in your portal. Those templates can now include ClickHelp-specific entities like conditional blocks, automatic navigation elements, etc. Just create them as regular topics and create new topics as their copies. Topics used last for copying are preserved in the Recent Items list. Also, since ToDo items and review comments are copied as well when a topic is copied, you can add them to such "template" topics in order to provide a checklist for new topics, some hints or topic workflow for authors or whatever additional information you find necessary.
You can now change topic workflow fields (Status, Assigned To, Owner) in the view mode, without locking a topic.
It is now possible to see the number of unresolved review comments, and the comments themselves for a topic, without switching to the editing mode thanks to the new Review Comments dropdown invoked from the topic header.
Topic editor header now displays various metrics for the currently selected article. You can select 3 metrics you currently need out of 35 various metrics available. The list includes text metrics (unique content percent, words / characters / sentences count, etc.), readability metrics (time to read, Flesch Reading Ease, Flesch-Kincaid Grade Level and others), item count metrics (the number of links, images, tables, snippets, conditional blocks, etc. in the current topic). All readability metrics (except for the New Dale-Chall Score) are available for all languages, even though the formulae were originally designed for the English language.
All topic metrics are also available on a separate topic properties screen. This way, you can switch between topic and check all their metrics easily.
It is now possible to use ClickHelp-specific entities like conditional blocks, snippets, variables, automatic navigation blocks, etc. in topic headers and footers defined in the Topic Master Page settings. So, if you need to edit your headers/footers visually you can now insert a snippet just once into your project settings and then edit that snippet as a regular topic. And if you want to add some automatic navigation to all your help topics with a few simple actions, you can do so through project master page settings as well. Related change: header and footer settings specified at portal level no longer affect publications, they are applied to projects only. When a publication is created, it gets header and footer markup added to topic content from project settings. So, the headers and footers cannot be changed in the publication settings after publishing, they become a part of the topic content.
It is now possible to insert code samples with automatic syntax highligthing in your help topics easily, which is particularly useful for API documentation. The editor used for code examples creation supports 40+ programming languages and provides all the major features ClickHelp source editor has, including automatic formatting and newly introduced automatic formatting for JSON data, particularly useful when describing REST APIs. The generated markup also includes the "Copy Code" feature for your readers' convenience.
Mini-TOC elements are now generated and updated automatically. Indentations were introduced for mini-TOC links to indicate the heading level in the hierarchy. Also, it's possible to specify the maximum depth of headings which will be used for mini-TOC generation and the CSS class which will be used for the mini-TOC (if it's necessary to customize a specific instance style).
It is now possible to insert special symbols in your help topics easily with the new Insert Symbol dialog. You can use keyboard shortcuts to invoke the dialog and insert recently used symbols without touching the mouse.
It is now possible to see all resolved and deleted comments for a topic. The comments along with the information on who and when resolved/deleted them are displayed after unresolved comments in the new Review Comments dropdown. While unresolved comments are sorted in the order in which they appear in text, resolved/deleted comments are sorted in the order in which they were resolved/deleted (latest go first).
It is now possible to edit and delete specific replies in the review comment threads.
All topic headings without explicitly assigned IDs now get IDs automatically assigned to them. When a heading is hovered, a link icon appears which can be used to retrieve an anchor link for the heading quickly.
When creating an anchor link in the Insert Link dialog, you can now see the text associated with the target element. If the element has no text, you see its ID. Also, the dropdown now includes information on html tag name of the target element.
Content pasted from Microsoft Word and other rich edit editors is now optimized better (unnecessary tags removed).
The topic editor loading speed has been significantly improved.
Topic loading UX significantly improved. Specifically, loading placeholders are used, and the Login page is no longer displayed in the right panel when trying to open a password-protected topic via a hashbang URL.
Images having review comments associated with them are now highlighted with orange border.
It is now possible to use anchors in smart links.
The Style combo box and other CSS class selectors no longer contain CSS classes from ClickHelp templates and only include custom user styles. For tables, the CSS class list also includes a few template CSS classes if they're still present in your style files.
Special CSS classes are now added automatically to all videos inserted in topics so you can control their styles and sizes in a single place through CSS.
Table editing made easier: context-sensitive popup for tables now offers popular functions like inserting or deleting rows, etc., so you always have them at your fingertips. Also, the Table tab of the editor is now a context tab which is only displayed when the caret is located inside a table. The tab is automatically selected when you insert a new table.
Context-sensitive popups with element-specific commands implemented for all common elements: links, images, table cells, popups/dropdowns, automatic navigation elements, See Also elements, conditional blocks, snippets, variables, etc.
It is now possible to create a comment for the current block if no text is selected and the Add Comment command is clicked.
Added the Insert Comment command to the Insert tab of the editor ribbon based on usability tests (people expect to see it there).
When inserting a snippet and there are not enough matching items to show in the snippet selection dropdown, the dropdown now suggests topics which were used as snippets recently. Previously, topics recently viewed by the current author were suggested, which were often less relevant.
Current element style name is now displayed in the Style combo box on the topic editor ribbon, like in MS Word.
Placeholder styles were updated for variables, snippets and conditional blocks. Also, border color is now used to indicate the block type where applicable (gray for snippets as usual, green/red for include/exclude blocks).
Editor is now focused automatically when entering the editing mode.
Based on usability tests, changed the color and caption of the "Lock&Edit" button.
Topic link icon in the editor header moved down, to the topic title (like in the reader UI) to make the UI more intuitive.
Added context help links to the topic properties screen to provide additional information on how the "Show in TOC" property and publishing properties are inherited.

The TOC now includes indicators for the number of unresolved ToDo items and review comments associated with each topic. The indicators also indicate whether a TOC node has any children with unresolved ToDo items or review comments.
The TOC now includes indicators for TOC node publishing types (publish never, conditional include/exclude). The indicators also demonstrate the fact that TOC node publishing properties are inherited from parent nodes to children.
It is now possible to delete multiple nodes with a single action (new action added to the context menu).
Both readers and authors can now expand/collapse all TOC nodes easily via the new Expand All / Collapse All commands available from the TOC toolbar.
Authors can now change workflow fields (Assignee, Owner, Status) for multiple topics in a single operation via the new TOC toolbar commands. This is particularly useful when importing a manual in which all topics should be marked as Ready.
TOC performance dramatically improved.
When filtering TOC nodes by titles, non-matching nodes which are still displayed (because they're parent nodes for matching nodes) are marked with gray color.
Extra space added at the bottom of the TOC to ensure the last TOC nodes remain accessible and the Create New Topic button does not overlap them.
When drag-n-dropping a TOC node as a child of a node which is not always published, the new child node gets inherited parent settings assigned explicitly to it. As a result, if you move the node to a different parent which is always published, or its parent publishing type changes, the child node will keep its old publishing type settings. The logic is similar to how the "Show this node in TOC" option is handled - for this option, when a parent is removed from TOC, the setting is assigned to all children automatically. However, when the parent is added back to TOC after that, its children are still not shown in TOC. The same applies to publishing/not publishing TOC nodes.

Publishing

New publishing mode introduced: Partial update. This mode can be used to update one or more topics in an existing publication without re-publishing the entire project.
It is now possible to publish a single topic instead of publishing the entire project. This approach is particularly useful for knowledge bases, policies & procedures, internal instructions and other cases when documents are updated one by one.
It is now possible to publish a set of explicitly selected topics instead of publishing the entire project. This approach is useful when you need to update a part of your manual while other previously published parts are not ready for the update yet (and should remain the same in the publication), or when you need to export a specific set of topics quickly.
Publishing wizard redesigned to make the publishing and export process more straightforward. Now, you can select the desired output format on the first step of the wizard and you only provide minimal input required for each of the formats. Also, the PrintedDoc output tag is now assigned automatically when selecting a printed output format in the wizard.
All topic and file links in topic content, styles and scripts are now validated when copying or publishing a project (previously only snippet URLs, variable names and output tag names in conditional blocks were validated). If a format other than "Online documentation" is selected, a temporary Private publication is created and then deleted automatically after the export process ends. However, the process remains as it was if you export an existing publication (publication is NOT deleted).

Full-Text Search

It is now possible to exclude specific topics from full-text search results with a new option added to the Topic Properties screen. This feature is especially useful for Context Help topics which should not appear anywhere in navigation, but must sill be available in a publication.
Wildcard support implemented in portal search. Now, it is possible to search for incomplete terms, like "tool*". Wildcards are only allowed if there are at least 2 non-wildcard characters in a word, otherwise the word gets ignored. Also, a query cannot contain more than 2 words with wildcards. 3rd and further words with wildcards in a query are ignored.
The "Search entire portal" item is now displayed in the search dropdown in application header if no results were found while searching a specific project/publication, but there can be some results found via portal search.
Search results relevance improved.
Index Keywords can be used to fine-tune Full-Text Search results explicitly in the UI.

Import

HTML files exported from Confluence are now handled specially to remove Confluence-specific header/footer and generate cleaner markup.
HTML/CHM files generated by Dr.Explain are now handled specially to remove master page, generate cleaner markup and import Dr.Explain styles precisely.
When importing a manual with folders as a set of HTML files, the folder topics named as "index.html" now have URLs coinciding with the folder name. For example, a topic located in "My Folder\my topic.html" will have an URL of "my-folder". Cross-topic links are updated automatically and remain valid in this case.
Styles are now optimized better (unnecessary tags removed). This leads, for example, to the ability to style all imported headings in a centralized way with a few lines of CSS since imported headings no longer contain inline styles.
It is now possible to select the format in which images will be imported to ClickHelp from printed formats (Word, RTF, etc.).
Import wizard updated: added information on the XHTML and Web Help formats support for HTML import.

Web Help

Web Help engine redesigned to provide better indexing by Google, Bing and other web search engines. The change includes but is not limited to the usage of HTML5 semantic tags in the UI.
Web Help UI updated to provide more modern look and match portal UI better.
It is now possible to print Web Help topics opened from a local file system, not just those hosted on a web server and accessed via HTTP.
Search results in Web Help now include snippets of topic text.

Workflow

Added email notifications for ToDo items created, deleted and marked as done. The notifications are sent to the assignee and owner of the current topic, plus to the author who created the ToDo item.
Each user can now control their own notification settings instead of using global portal-wide settings to decrease the number of email notifications sent by ClickHelp.
When a review comment is deleted, an email notification is sent just like for situations when review comments are created / resolved.
Status colors are now used to make the current status more visual in all topic-related email notifications.
Adjusted the styles of email notifications for workflow events and review comments to make them easier to read. Also, notifications on review comment events now mention the event explicitly in the email body, not just in the subject line.
Email notifications on topic changes now contain the name of the project to which the topic belongs.
Email notifications for all workflow events are now delivered faster (queue timer changed from 5 minutes to 1 minute).

Export

It is now possible to define the "Start from new page" setting in the Export wizard (both when using Word templates and when using Export Configurations). The setting defines default behavior for topics which don't have the "Start from new page" option specified explicitly.
Newly created portals will now have two printed output export template files: one for the A4 paper size and another one for the Letter paper size. If you own an existing portal and need to get the Letter paper size template, please contact us and we'll provide you with it.

Reporting

Reader Count report implemented: now, you can see the number of unique users who visited your documentation during a specific period of time. Information is provided for each publication separately. Also, if you are using the Restricted Manuals feature, the details table for the report will provide information on which specific Power Readers viewed your documentation. Using the standard reporting features, it is also possible to group/filter/sort the topic views by readers, reader roles, projects, etc.
Project Readiness by Review Comments report implemented: now, you can see how many unresolved review comments are left to handle for projects, topics, authors and reviewers. It is also possible to see the number of resolved/deleted review comments in the report for auditing and work tracking purposes.
Topic Metrics reports implemented: Text Metrics, Readability and Item Count. Each of the three reports allows you to see how your topics are distributed by values of this or that metrics, as well as drill down into details on each of the 30+ metrics available.
User list reports improved: the reports now include headers/footers, the report table now fits page width and the "Enabled" column labels are now shortened (just "Enabled / Disabled", without hints) in exported reports.

Settings

It is now possible to change Home page background image easily via selecting it visually.
It is now possible to edit the Home page styles which are a part of the Home page template.
It is now possible to hide the quick filter box displayed above the TOC via Reader Experience settings.
It is now possible to upload new SSL certificates for existing portals via Domain Mapping settings.
It is now possible to hide the Index Keywords navigation panel for readers even if there are index keywords defined for a publication. This feature is useful when you don't use index keywords for navigation, but use it for full-text search fine-tuning instead.

Dashboard

Reviewer Dashboard now includes project/publication icons indicating the type (project/publication) and visibility (Private/Restricted/Public) of the project to which a topic belongs in order to avoid confusion between topics in projects and publications.
Values in the Project column on Reviewer Dashboard are now links, so reviewers can open projects easily in one click right from the Dashboard screen.
Dashboard start page redesigned for cases when there are no projects in the portal.
Context menu items for publications are now always visible, you no longer have to hover mouse pointer over a publication to see them.
Added information on when a publication was created to the Publications panel.
"Publish the ... project" placeholders are now always available in the Publications panel, even if publications already exist for the project.
The "Topics" context menu item for projects and publications renamed to "Open" to avoid confusion.
Renamed the "Files" context menu and navigation bar item to "Images and Files" to use the same term as in File Manager.
Added the "Open in new tab" link in the publication link popup window.

File Manager

Performance dramatically increased for huge storages, especially those having thousands of files or folders at the same level of hierarchy.

User Management

It is now possible to change user logins from user profiles. This allows, for example, changing names for users you no longer need to make their names available for new users of a different type (a.g. authors or reviewers).
It is now possible to specify Author, Reviewer or Power Reader role right in the author creation dialog, without the necessity to open the newly created author profile.
The default role for all newly created authors is now Administrator, not Author. Can be changed easily in the author creation dialog if needed.

API

It is now possible to download Storage files, including password-protected files, through the REST API (the Basic authentication mechanism is used).
Users having the Author, ProjectLeader and ProjectsManager roles now have the capability to use ClickHelp API (if the REST API feature is included to your plan). Previously, only Administrator users could do that.

Security

New authentication scheme implemented: one-time tokens. If you do not want to configure SSO, but need to log users of your website / application seamlessly into ClickHelp, there is now an easy option for you which does not require much work.
A ClickHelp portal now can act as a multi-tenant Azure application when using OpenID Connect to login.
Security enforcement: downloading a file from a project/publication folder now requires the user to have access to this project/publication. So, project/publication files are now password-protected, just like topics.
All HTTP requests to ClickHelp portals are now redirected to HTTPS when possible to prevent insecure communication.

Other Improvements

Improved accessibility (section 508) compliance.
Overall performance optimizations, especially for slow Internet connections.
All project templates now include an automatic breadcrumb in the header and a customizable sidebar with automatic mini-TOC and See Also elements.
Changed the default behavior of the Delete Project wizard: now, project folders in Storage are deleted by default when a project is deleted.
Added an option to preserve workflow field values (Assignee, Owner, topic status) when copying a project.
Added the "Current Project | Images and Files" main menu item for easier navigation.
The "topic URLs" concept referring to alphanumeric IDs used to generate topic URLs replaced with a more precise "topic IDs" term to avoid confusion.
All article selectors (Insert Link dialog in the topic editor, cover topic selector for export configurations, etc.) now search for topics by their alphanumeric IDs as well, not only by titles and full URLs.
Added a number of context help popups and links in various parts of the UI to make it more clear.
Changed a number of icons to give the UI a better / more modern look.
Updated loader styles for better perceived performance.

Fixed Issues