ClickHelp Documentation

Reviewer Roles and Permissions

Reviewing is an essential part of the working process. In ClickHelp, you can conduct your documentation review before it goes live; you can give your reviewers access to specific projects only. This is all possible with ClickHelp!

To learn how to manage reviewer permissions, keep reading:

Creating a Reviewer Account

To create a new Reviewer user account, do the following:

  • Click Tools  Users and Roles in the main menu.
  • On the ClickHelp User Accounts page, select the Reviewers options group on the left.
  • Click the Create Reviewer button.
  • Specify the account details in the Create New User dialog and configure the access level.
  • Once you click OK, the system will create a new Reviewer account.
  • Login information will be automatically sent to the email address you specified in the account settings.

Managing Project Access for Reviewers

The most common working process is doing a review in a Project. When doing a topic review, it is recommended to keep the topic author as the topic Owner so this user gets email notifications about all review comments and status changes.

When the topic is ready for review, change the status to Under Review and assign this document to a Reviewer. The Reviewer will receive an email notification that contains a link to the topic. The Reviewer will follow the link and log in to the Reviewer Dashboard. If the topic content is acceptable, the Reviewer will assign the topic back to the original authors and change the status to Ready. If the Reviewer has some feedback that needs to be handled, they add Review Comments, assign the topic back to the author and change the status to Draft. The topic Owner (presumably, the content author) receives email notifications with every Review Comment and another email notification when the topic is assigned back to the author.

When you assign the topic to a Reviewer, ensure that this Reviewer has access to the project. You can do it in different ways:

  • On the topic editing page.
    In the top menu, click Current Project  Settings  Visibility & Access and give access to the Reviewer if necessary. 
    Set the access to a particular reviewer in the project settings
    Then click Save Changes.
  • On the Author Dashboard page.
    Click the ellipsis menu button under a Project name as it is shown on the screenshot.
    Click the ellipsis menu button to get to the project settings
    Then go to Settings  Visibility & Access. Select Reviewers that will have access to the project. Click Save Changes.  

Moreover, if you work with several Reviewers, you can create Reviewer Groups and control which projects they have access to. To learn more, read the Reviewer Role Permissions section.

Doing Review in a Publication

Project content may be dynamic because topics contain conditional blocks, variables, and snippets. When publishing a Project, authors may use Output Tags, so Publications created for the same project with different output tags may look differently. Reviewers may not know what combinations of output tags are used when publishing and hence may be unable to figure out what the final output will look like. This may affect their possibility to provide meaningful feedback during the review cycle. In such situations, consider running your review cycle in a Private Publication. Here is the process:

  • Let's assume you have a project that should be reviewed, and there is a lot of dynamic content in it.
  • To create a Publication, click the Publish button below the project name.
  • Step 1 of the publishing wizard sets the visibility level to Private. Use the Configure Access button on this wizard screen to configure access permissions for the publication you are creating. By default, your publication will be available to all Authors and all Reviewers.
     Set the publication as private in the Publishing Wizard
  • Proceed with the further wizard steps as you usually do when creating a publication.

Reviewer Role Permissions 

If you need to give access to a group of Reviewers, you can create and use Reviewer Roles.

To create a Reviewer Role, follow these steps:

  1. In the top menu, click Tools  Users and Roles
  2. Select Reviewer Roles in the left-hand navigation bar on the user management page that opens.
  3. Now click the name of a Reviewer Role.
  4. Then specify which Projects and Private Publications are available to this Reviewer Role:
    Select the publications available for a group of Reviewers in the Role Editor
  5. Click Save Role.

Later on, when you need to change permissions for a group of Reviewers that have a specific role assigned, follow the steps described above. As a result, all Reviewers who have this role assigned will have their access permissions changed.

Granting Individual Access

Despite having some permissions defined in a Reviewer Role assigned to a user, you can also manage permissions for an individual user within that role. For example, all users with the Reviewers role have access to Making robots Publication only:

Select the publications available for a particular Reviewer in the Role Editor

To grant additional access to the Harry user, select that Reviewer user and click the Edit user's profile button:

Click the Edit user's profile button to change the user's profile

As you see, the role of Reviewers is assigned to Harry and William. According to this role, they have both access to Making robots Publication:

See the Reviewer Roles and available publications in the user's profile

But you can give additional permissions to Harry so that this user can access the My Software Documentation v. 1.4 guide - check the needed project or publication in the list and click Save Changes:

Set the individual access for a Reviewer in the user's profile

Another user with the same role will not have access to this publication because of the change; only Harry will have it.

Changing the permissions on the user level does not change permissions for other users with the same role. Instead, user-level changes apply only to that specific user, and the role-level permissions merge with the user-level permissions.

Specifics of Private Manuals  

When creating Private Publications, you should be aware of a few things:

  • If an anonymous reader tries to access a restricted manual using a direct link, the system will direct them to the Login page.
  • Private Publications do not share any content with the project they were generated from. So, when conducting your review in a Private Publication, make sure you make changes to the corresponding project rather than to this publication.
  • Since Private manuals require logging in, they are not indexed by search engines. This means that those manuals cannot be found in Google, Yahoo, Bing, etc. If you expect to get some SEO benefit from online documentation, make sure you restrict the access wisely.