A clear and flexible review process is a highly demanded feature for a help authoring tool. This comes as no surprise as reviewing directly influences the quality of documentation. Which, in its turn, affects a company’s credibility.
In this post, we will talk about best practices in reviewing technical documentation and take a closer look at how this feature is implemented in ClickHelp, a cloud-based tool for technical writers.
Documentation Review: General Information
A review process is unique for every company, that’s true. The idea behind it though remains the same: after a help topic is written by a tech writer, it should be redirected to a reviewer. The latter checks the content and creates comments when necessary.
Reviewers can be of a different kind. Some make sure that technical aspects of documentation are correct and in tact. Others can, for example, check grammar and punctuation only.
A reviewer’s job is to make documentation more precise and effective. BTW, measuring a user manual’s effectiveness is an interesting topic on its own, check out this blog article to figure out how to actually do this.
It is a challenging task to create a universal review feature that could meet requirements of different documentation teams. After careful consideration of possible customer needs, the ClickHelp devs managed to come up with an approach to the review process that seems to be quite flexible and universal. Keep reading to learn more.
Adding Comments
We will get into some technical stuff later, for now, let’s take a look at the very core of any review process - adding comments.
In ClickHelp, this part is very intuitive. All a reviewer needs to do is select the word in question and click Add Comment.
For better visibility, words or phrases that have been commented on are highlighted.
Deleting a comment is just as simple - take a look at the screenshot below.
So, since this part is clear, let’s dive into a more serious discussion - who is supposed to review documentation?
Roles and Permissions
When a draft gets written by a tech writer, it should be then assigned to a reviewer. Quite often, these are people with more expertise in this area.
And, sometimes, reviewers are not even tech writers. They are not supposed to create or change topics, all they can do is leave notes for further consideration.
In ClickHelp, you can assign reviewer roles to team members and set up permissions for them. After that, reviewers can be picked for different projects as shown below:
This helps team members to become more clear on what the scope of their responsibilities is. It also helps to avoid unwanted activity and makes the whole work process more manageable.
Keeping the Process Flowing
Without the right tool at hand, reviewing can be very frustrating. You see, sending docs for review via email is, sadly, still a thing in some companies. This approach can cause confusion and major delays as documents are hard to track in email clients.
In ClickHelp, we have thought this whole process through, and here’s what we have to offer:
- all topics have a status (like: draft, under review, and ready);
- email notifications are sent when a topic status is changed / a topic is assigned to someone;
- topics are automatically locked for other users while somebody is working on them;
- there’s a special dashboard for tracking statuses of all topics.
All this allows avoiding confusion and keeping thing in order.
Let’s talk a bit more about the Reviewer Dashboard, a great feature that allows seeing the whole picture:
The dashboard of our technical writing tool has all the information you might need in one place. Also, it can be filtered using either default filters or custom ones.
Conclusion
As you can see, there are ways to improve a review process no matter how many projects you have, or how many people are involved.
Once everything is set up in ClickHelp according to the needs of your team, reviewing becomes a piece of cake, meaning that your reviewers won’t have to worry about missing or forgetting anything anymore. They can just relax and do the job - the rest is taken care of.