ClickHelp Documentation

Typical Help Authoring Process


The goal of any help authoring process is to get a user manual in the end. In ClickHelp, everything starts with creating a project where you write the content. And the final goal may be interpreted as getting a user manual published online and accessible to readers - that is, publishing your project to create a publication. Depending on the structure of your technical writing team, the path from project to publication may vary. ClickHelp does not enforce one specific workflow - you choose how to work on a project to get the final goal achieved. In this topic, we will learn what a typical process looks like and what parts it contains.

Typical Help Authoring Process Scheme

Create a Project

When you start working on a user manual, the first step is to create a new project in ClickHelp. The project will be the container of the help topics you create and the place for technical writers to collaborate.

Click New Project... on the Projects page to open the project creation wizard.

When creating a new project, you can select any of the existing pre-designed templates. You will be able to modify the project style later, no matter what template you select.

Create Help Topics

Upon project creation, select it in the projects panel, and click Open Selected Project on the toolbar - the project editor will open.

You will see the table of contents on the left side of the screen in the Contents panel. On the right side, there will be the selected topic body. To create a new topic, just click the Create New Article button on the toolbar of the Contents panel. A new topic with default content will be created and opened.

To modify the topic contents, click the Edit button in the top-right corner of the screen. Once you do this, the current help topic will be locked for other authors, so they can't interfere with you while you are working on the content. The topic contents will switch to the editing mode.

If you take a look at the bottom of the topic editor, you will see three tabs:

  • Design - this is the visual editor of the topic contents. In this editor, you can perform all typical content creation and editing tasks.
  • Source - shows the HTML source of the help topic. Useful when you need to use tricky CSS effects or implement some non-standard layout.
  • Preview - shows a preview of the final output, expanding all variables, snippets, and conditional blocks. May be used to quickly check how the topic will look like in various publish configurations.

Configure Look and Feel

To make your documentation portal better match your company style, check the Branding options group in global settings. Specify the favicon to show in the browser header, your logo, and other settings.

One more thing you may want to modify is the documentation portal home page - this is the page that is shown when your readers navigate to your portal URL without opening any specific help topic. For example, this link points to the home page of our documentation portal:

Assign Topics to Reviewers

When a help topic is ready, you can assign it to a reviewer - a subject matter expert, a technical editor, documentation team manager, etc. This is done by changing the Assignee field and setting the status to Under Review. Using statuses is not required, but may really be helpful to make it easier to see the project progress, filter topics in the Contents tree by statuses, see the topic distribution by statuses in the project statistics, etc. When a review is completed, the reviewer will change the topic status to Ready, and assign it back to the topic owner.

If reviewers have notes or questions about the topic contents, they can add Review Comments for the owner to handle them.

Whenever a topic is assigned to a user, an e-mail notification can be sent to the assignee - you can control this behavior in your portal global settings. Those notifications may include several latest review notes as well to give some context to the assignee.

Publish your Online Manual

When all help topics are ready, you can finally publish them to make them accessible to readers. To do this, you select the project on the Projects page and click Publish/Export on the toolbar. In the wizard that opens, you specify what you want to do - only publish the manual, or publish and then export to a printed format. Note that you can export any publication to a printed format later, after publishing.

In the publishing wizard, specify the visibility of the publication being created. You can publish in the Private mode for final review, and then change the publication visibility to Public later in the publication properties.

The publication name you specify in the wizard will be visible to the readers, so make it self-descriptive.

Export to Printed Formats

You can export any publication to one of the supported printed formats: PDF, DOCX, ODT, ePub, etc.

To do this, select the needed publication in the projects tree, and click Publish/Export on the toolbar - the publishing wizard will open. You will need to specify the format first. One other important thing is the export configuration - if you don't have one yet, you might need to create one. Export configurations store the exporting settings for further re-use.

On subsequent steps of the publishing wizard, you can configure many style-related parameters to make sure your printed documents look good.

Track Statistics and Improve Content

ClickHelp provides statistics both for projects and for publications, though the parameters collected are different.

Project statistics can help you understand the project progress and readiness. It shows article distribution by statuses or by topic owners - you can see how many topics are ready, and how many are still in the works.

Publication statistics show how many views each help topic gets, and how readers navigate to that topic. It will also show you the topic ratings if readers are voting for topics. It may help you identify those topics that need to be improved, and perform additional review of that topic.