ClickHelp User Manual

Release Notes: January 2018

ClickHelp January 2018 Update


In this update, we introduce a new Team Review process with a special Reviewer role. You can now easily give read-only access to your colleagues so they can add review comments, change topic status, reassign the topics, add ToDo items. The Reviewer users cannot directly modify the topic content.

To help teams manage their documentation projects, we have added a new Report Center that provides valuable information on key metrics: project readiness charts, author contribution stats in words and topics created, stats on topic views made by your readers, the list of search queries your readers perform including the number of results they get and how many clicks they perform.

To further improve user experience, we re-worked the Projects page of the Auhtor UI to make it more functional and useful. Meet the new Portal Dashboard page! Keep reading to learn more on other great features we've added.


New Features

    User Management

    • New user type implemented - Reviewers. Reviewers can see projects and Private publications and leave review comments for pieces of text in topics. They can also change topic statuses and re-assign the topics. However, they cannot edit topic content.
    • It is now possible to assign multiple roles to a single Power Reader or Reviewer user. This allows combining permissions on large user sets easily.
    • It is now possible to export user list for each user type: Authors, Power Readers and Reviewers. Supported export formats are PDF, XLS, XLSX, CSV and RTF.
    • When using multiple OpenID Connect providers for Single Sign On, it is now possible to specify a specific SSO provider which will be used by a specific user to log in to ClickHelp explicitly, without making the user see ClickHelp login page and pick the needed provider from the list.
    • The Last Activity Date data is cleared for all user accounts with this update. This is due to a switch to a new, more precise, activity tracking system and fixes of known issues.
    • It is no longer possible to create users whose names contain the <, > or & characters.
    • If your ClickHelp plan does not include Author Roles, all authors are created with administrator permissions.

    Reporting

    • Report Center implemented. It provides a number of reports on your content, team workload, reader behavior, etc. Here are just some of the features common for all reports:
      * Charts with data visualization.
      * Chart filtering by legend items.
      * Chart points grouping by days, weeks and months (where applicable).
      * Grids with detailed information.
      * Sorting, grouping, custom filters and data search capabilities.
      * Group summaries showing the total number of topics, added words and other values for data groups.
      * Quick filters by dates and projects/publications (where applicable).
      * Data export to PDF, XLSX, XLS, CSV and RTF formats.
      * Filtering settings persisting for each user.
      * Filters stored in URLs - users can share links to specific reports with specific filters.
    • New report types:
      * Reporting dashboard that gives you a big picture of how your portal is performing.
      * Project readiness - a report showing topics distribution by statuses, grouped by projects or authors.
      * Words added by authors - a report that gives you the total number of topics updated and words added to each topic during the given period of time, grouped by authors and projects.
      * Top contributors by words - a simple rating of authors ordered by the number of words they added to help topics during the report period.
      * Words added by projects - the number of words added to each project during the given period, with breakdown by specific topics.
      * Topics created by authors - a report that gives you the total number of topics created during the given period of time, grouped by authors and projects by default.
      * Top contributors by topics created - a simple rating of authors ordered by the number of topics they created during the report period.
      * Topics created by projects - the number of topics created in each project during the given period.
      * Topic Views and Ratings - detailed report on all topic views in the portal during the given period. Gives total data for each publication when viewing portal report and detailed data including navigation sources breakdown for each topic's views when viewing report for a specific publication.
    • Topic views produced by web crawlers and various bots are now filtered better, so you get more precise statistics on real human interactions.
    • Search Queries - report on the number of full-text search queries during the given period, grouped by projects with information on the average search result count and the number of result clicks.
    • Data cleanup: topic views produced by web crawlers and bots prior to this version have been removed from all portals.
    • Publication topic views produced by authors are no longer tracked and removed from all portal DBs.

    New Portal Dashboard

    • The page contains information on the total number of projects and publications along with brief reports on the latest actions with them.
    • The page contains three widgets: Recent Documents, Project Readiness report and the Top Contributors report.
    • New projects list control makes the distinction between projects and publication clear and gives better context for main actions on projects and publications - each of them now has its own set of actions associated with it.
    • To make initial learning easier for trial users, the portal dashboard page now contains a trial achivenements widget that displays information on main steps which should be completed during a trial along with information on how to accomplish them.
    • You can now get links to publications on your portal easily with just a few clicks - hover a publication, click the link icon, then click the dropdown and the link will be copied to your clipboard automatically.
    • It is now possible to view specific project's files easily by selecting the specific project's Files item in the left navigation menu on the Dashboard.
    • The Dashboard also provides access to the File Manager for the entire portal's storage in the form of a panel, not a dialog.
    • It is now possible to obtain your ClickHelp portal URL easily via clicking a link icon in the Portal Dashboard header.
    • For Reviewers, the Dashboard contains a list of topics they need to work with - with grouping, sorting and filtering capabilities. Predefined filters can be used to handle a number of typical workflows. All list customizations are preserved, so a reviewer needs to configure it just once.
    • Publish Project wizard performance dramatically improved for portals having thousands of Power Readers.

    Topic Editor

    • Authors and Reviewers can now leave comments for specific words and phrases easily. Each highlighted topic fragment can be associated with a thread of comments from multiple users. When comments are no longer needed, they can be either deleted or resolved.
    • Link Viewer implemented. It is now possible to see a list of all links from/to selected topic. Supported link types include topic links, Storage file links, styles and scripts links, project links, external links (HTTP/HTTPS/FTP and other protocols), links from Export Configurations, etc.
    • It is now possible to see broken links in help topics via the "Links from topic" report in Link Viewer.
    • Content pasted from MS Word, MS Outlook and other rich text editors is now optimized via the same logic applied during import from printed formats. This gives much cleaner HTML markup, which is much easier to maintain, while preserving the visual styles.
    • It is now possible to paste content with images from MS Word, MS Outlook and other rich text editors. Images from the pasted content are now uploaded to the project's folder in Storage automatically, just like it's done for regular image pasting.
    • Getting topic links is now easy both for authors and readers - the link icon in topic header now shows a popup with a topic link which can be copied to your clipboard with a single click.
    • It is now possible to get links to all published versions of a topic easily. When clicking the link icon in topic header for a topic in project, you now get a full list of links for this topic in all the project's publications.
    • The Review Notes panel replaced with a new TODO panel which stores TODO items with done/not done statuses for specific topics. All existing Review Notes are converted to TODO items during portal upgrade and marked as Done. Reviewer users can create and check/uncheck TODO items too, but unlike author users, they cannot edit or delete TODO items created by other users.
    • It is now possible to resize tables and images by dragging visual resize markers in the editor.
    • New element implemented: popup. Now, it is possible to create hidden content sections which will appear as popup windows when an associated hotspot is clicked. Popups can be copied between topics and edited visually in the Design mode.
    • New element implemented: dropdown. Now, it is possible to create hidden content sections which will appear when an associated hotspot is clicked. Dropdowns can be nested, copied between topics and edited via popup windows in the Design mode.
    • It is now possible to control content line spacing in the Design mode.
    • It is now possible to control spaces before / after content blocks in the Design mode.
    • Is is now possible to insert links to topics from other projects in Design mode. The links are inserted as Smart Links automatically and are resolved to the latest publication of the referenced project for readers.
    • Editor performance was significantly improved for portals having thousands of Power Readers.
    • Automatic formatting of topic sources dramatically improved: a new smarter algorithm is now aware of difference between block tags (like <p> or <table>) and inline tags (like <a> or <b>). So, unexpected line breaks are no longer produced for inline tags. Also, empty lines between block tags which were separated by whitespaces (like </p> <p>) are no longer inserted.
    • Topic URL is now displayed for hovered item in the Insert Link dialog, Insert Snippet box and other places where topics are selected. This helps identifying the correct topic easily if you have several topics with the same title in the same project.
    • It is now possible to specify custom URL parameters in article links. Just add the name/value pairs after the topic ID: .../welcome-topic/param1/value1
      Such parameters can be used to pass any custom data that can then be handled in your branding or project scripts. For example, you can now make topic cnotent variable: passing customer-specific values for placeholders (e.g. "My user name") via URL parameters will allow you to customize help topics depending on which user navigates to them from your website or application.
    • Removed spell checker language selection combo box from the ribbon to free some space on small resolutions. Project language is now used to set the spell checker language automatically for topics.
    • Pasted images are now visible while being uploaded (previously, a placeholder was displayed instead of them during the upload process).
    • Topic status and assignee notifications improved: the To field now contains user's first and last name to decrease the chance of notifications being marked as spam by mail servers.

    API

    • Breaking change: the task status object returned by requests to the /api/v1/tasks resource changed:
      * the maxOverallProgress field now always returns 100;
      * the overallProgress field now returns values from 0 to 100 (the value type is still integer).

    Topic Workflow

    • ClickHelp now supports custom workflow statuses. Status names, colors and allowed status transisitions can be configured by ClickHelp support team per customer request. Please contact us if your subscription allows custom statuses and we will set them up for you.
    • When a review comment is added for a word or phrase in a topic, an automatic notification is sent to relevant users (except for the user who made the change). When a comment is added, notifications are sent to the assignee and owner of the topic.
    • When a review comment thread is resolved, notifications are sent to each person involved in the comment thread.
    • Workflow notifications updated with information on how their settings can be changed.
    • Updated styles for all notifications sent by ClickHelp.

    Table of Contents

    • If a predefined TOC filter (like "Assigned to Me") is selected, the filter name is now displayed in the filter box (was just "[Custom Filter]" previously).

    ClickHelp UI

    • The Projects page was renamed to Portal Dashboard and redesigned from scratch. The new page gives a better understanding of the current state of your portal and provides some brief stats on projects and publications inline.
    • In-app chat support is now available for trial users during the evaluation period.
    • If a feature is not available according to your current ClickHelp plan, you will now see a special placeholder with two options: request a quote and request a free trial of the feature.
    • Changed the design of the initial author screen - now, its main actions are explicitly designed as buttons rather than text links.
    • The portal Home page is now displayed for authors the same way it is displayed for readers to ease home page branding.
    • Main menu items renamed: "Portal Home Page" renamed to "Portal Home", "Projects" renamed to "Dashboard", "Current Project | Open..." renamed to "Current Project | Topics...", "Current Project | Statistics..." renamed to "Current Project | Reports...", "Tools | Global Settings..." renamed to "Tools | Portal Settings...".
    • Advanced settings in the Publish Project wizard are now always visible.
    • Main menu item added: "Tools | Report Center".
    • Added mobile screen handling for all navigation sidebars (Settings, Users, Profiles, Topic Properties, etc.) to make ClickHelp look better for authors using mobile / tablet devices or simply browser windows of small width.
    • Recent documents tracking logic changed: now, only the order in which documents were opened is important. Previously, the documents were sorted by the number of times they were opened and you could've seen a document in the recents list even if it was not opened recently. Due to this fact the list of recent documents is cleared for all portals with this release.
    • Topic ratings system redesigned: now, a popup suggesting to rate the topic is displayed instead of stars in the topic header.
    • All mentions of users across the application now use full names, not user logins.
    • Added help topic links to the majority of settings screens.
    • Added mentions of the fact that project name is visible to readers in all places where the name can be edited.
    • Shortcuts hint added to the Index Keywords editor.
    • The User Profile page is now fully responsive for readers using mobile phones.
    • Changed application theme to give it a more modern look.
    • A number of action icons updated to give the application a more modern look.

    Settings

    • It is now possible to configure publication filter behavior on the Search page. Instead of searching by specific publications, you can now allow your users to filter by projects. Search will be performed on all publications of the selected project which are available to the current user according to user permissions. If a project does not contain publications which are available to the user, the project will not be shown in the selection dropdown. This feature is especially useful for portals with a big number of publications (e.g. manuals for multiple versions of the same product).
    • It is now possible to use snippets, conditional tags, variables and other dynamic elements in topic headers and footers. This allows editing headers and footers visually and gives you the ability to make their content conditional (e.g. have different headers and footers for online documentation and PDF output).
    • Two new email notification settings allow disabling notifications sent when topic review comments are created / resolved.
    • It is now possible to specify the newly created project language when creating or importing a project.
    • Settings pages performance dramatically improved for portals having thousands of Power Readers.
    • Added a note with a help link regarding portal UI branding settings in the "Tools | Global Settings | Branding | Reader Interface" settings section.
    • It is no longer possible to change project URL from project visibility settings. Project copying is recommended instead as it allows updating all links in the project to the new URL automatically.
    • It is no longer possible to change a project's files folder in order to avoid confusion. The editor was replaced with a link to the project's Files page on Portal Dashboard.
    • Project/publication name can now be changed on the project visibility settings screen (was edited via the Projects page previously).
    • Editor height increased for page HTML editors (used to customize the Home page and various "not found" pages).
    • The My Subscription page performance dramatically improved for portals having thousands of Power Readers.
    • Added the Cancel button on the last step of the Export Configuration editor wizard.

    Full-Text Search

    • Different published versions of the same topic from multiple publications are now grouped into a single item in search results to avoid duplicates.
    • Topic URLs are now shown in search results to help end users differentiate search results having duplicate titles.
    • Following Google search behavior trends, the search box in application header and on the Search page no longer uses quick filter behavior to search by search queries which may not be typed completely yet. Instead, the search operation must now be triggered explicitly by pressing Enter or cliking the Search button.

    Export

    • Images located in table cells are now resized automatically to fit table cell width.
    • The {{TITLE}} placeholder is now supproted in Word template headers / footers. So, it is now possible to use the same Word template for multiple publications if you need to have the publication name mentioned in header or footer.
    • Export to Word, PDF and other printed formats: the Title metadata property is now populated with publication name.
    • Added warnings which help troubleshooting situations when zero or one topic gets imported from a Word document.
    • Added a warning on the Finish step of the wizard, which helps troubleshooting situations when exported MHT files are blocked by Windows security.

    File Manager

    • It is now possible to see where a file is used in your portal. This concerns both images/downloadable files and style/script files which can be used in portal settings or as project styles/scripts.
    • File preview area added to file manager. Now, it is possible to see preview of a selected file in File Manager dialogs. This is especially useful when working with screenshot images, which are usually large and hard to distinguish in thumbnails.
    • Selected file URL is now copied to clipboard automatically when being clicked in the File Manager.

    REST API

    • It is now possible to retrieve information on topic views performed by a specific Power Reader during the given report period.
    • It is now possible to retrieve information on full-text search queries performed by a specific Power Reader during the given report period.
    • Project/publication creation date is now returned via API along with other information. The Created On date is useful when you need to determine when the publication was last updated as a part of your continuous build process.
    • It is now possible to assign multiple Power Reader roles to a single user via the API. The API now also returns information on all roles assigned to a Power Reader.

Fixed Issues

    Topic Editor

    • When using the Element Properties dialog from tag inspector, unexpected borders could be added to elements.
    • Fixed an issue with videos embedded from Vimeo not working in Web Help opened from local file system.
    • Errors could be displayed instead of topics for authors when viewing a topic with Next/Previous links in some situations.
    • Smart links in topics are no longer converted to regular links automatically on each save operation.
    • Clicks on image upload area of the Insert Image dialog may could not show the file upload dialog in some situations.
    • The percent character in topic titles is now handled correctly when searching for topics by their titles in the Insert Link dialog.
    • If image size is defined via the width / height attributes, the size can now be reset to original image size correctly via the Change Image dialog.
    • If several paragraphs of text are deleted at the end of a long document and this operation is undone, the document is no longer scrolled to the top.
    • The Change Image dialog now displays correct image size if a custom size was specified for the image previously.
    • The Edit Style button on the Design mode ribbon now opens the first style in the project styles list. Previously, it could've opened not the first style if the first style file applied to the project was not located in the project styles folder.
    • The OK / Cancel buttons did not not work in index keywords editor under certain conditions.

    Reporting

    • Resolved an issue with duplicate topic views tracking for topics accessed by URLs without a hashbang.

    Import

    • Fixed an issue with CHM import failing due to "MSHelp 1.0 decompilation error" in some rare cases.
    • When importing a Word document with multiple duplicate headings, an error saying "Failed to generate a name for a new temporary folder" no longer occurs.
    • Import no longer fails if links in imported files contain characters which are not allowed in file paths with the "Illegal characters in path" error. Broken links are now reported instead.

    Export

    • Images are now auto-sized to fit page width correctly when exporting to printed formats and the images are not located inside table cells.
    • Links to topics from other projects (including smart links) now work correctly in all export formats (Web Help, PDF, etc.).
    • Topic references in Export Configuration settings (cover topic, insert TOC after specific topic) are now updated automatically when a project is published and thus tne "missing topic" errors no longer occur during export. Previously, topic references were not updated and it was necessary to update them manually before export.

    Version History

    • Fixed the "Object reference not set to an instance of an object" error which appears if you open versions comparison and the latest topic change is a title or workflow change (not content change).

    User Management

    • Last Activity date is now displayed correctly in user list when SSO is used for authentication.
    • Last Activity date is now displayed correctly in user list for users who log in under different user accounts during a short period of time from the same web browser. Previously, the activity date was only updated for the first user account in such situations.

    Table of Contents

    • Long words in topic titles are now word-wrapped on multiple lines in the TOC editor (were cut off by the TOC panel width previously).

    Full-Text Search

    • Angle brackets are now properly escaped in topic titles in search results.
    • Words separated by hyphen, underscore and other special characters (like "semi-automatic") are now handled correctly when searching in Web Help (gave no results previously).
    • When searching for a string containing the ' charater and opening a topic from search results, the topic is now loaded correctly.
    • Topics having diacritic characters in their titles are now displayed correctly in search results.

    Settings

    • Changes are now saved correctly when clicking the Save Changes button on the Portal Home Page settings screen while having the editor opened in the HTML mode.
    • Script files editor is now opened correctly when editing a project script file from the project settings screen.
    • The Home page customization panel is now fully visible even for situations when the home page content is empty.
    • The Settings page now redirects users without permissions to the Login page instead of showing the 404 page.
    • When saving Domain Mapping settings without a custom domain assigned, you are no longer redirected to the portal home page. If the save operation removed a custom domain assigned to your portal, you are now redirected to the Dashboard page of the default domain (*.clickhelp.co).

    Application UI

    • It is now possble to select English as the translation language in the Google Translate widget.
    • The hamburger icon no longer appears unexpectedly on the Articles page when the browser window width is 980-999 pixels.
    • The form autofill feature of web browsers is now fully supported by the Login page (previously, it was required to click the Password field after auto-filling the login form).
    • The Create Project wizard layout no longer gets broken after viewing template screenshot in full-screen mode.

    Other Fixes

    • Fixed the "Value cannot be null. Parameter name: path2" error which could have appeared on the last wizard step after a project operation (import / export, project creation, publication, etc.) has completed successfully.
    • A crash could occur when many users were trying to log in simultaneously.
    • When publishing a project, then deleting a project's publication and then opening the Publish Project wizard again, the updated publications list no longer contains the publication which was deleted.