ClickHelp Aurora Polaris update
by Bradley Nice, Content Manager at ClickHelp.com — software documentation tool
We did it.
For the past year, we worked tirelessly to bring you the best online documentation software possible. We turned our tool upside-down, added and rewrote an endless number of lines of code, drastically improved UI and overall user experience, implemented a bunch of cool features and did plenty of other stuff so you can create your documentation in a more efficient and easy way.
The changelog is so big that you could even call this a ClickHelp 2.0, but we decided to be more subtle and introduce the first themed release named Aurora Polaris. But it doesn’t mean we’ll unchain our programmers from the radiators in our basement — we will make sure to continue honing our tool and improving it even further until it reaches the unattainable ideal.
Get ready, as this one will be pretty long. So, shall we…?
Review and Collaboration
We heavily focused on review process during this update. After all, reviewing documentation written by tech writers is a necessary and very important step in its lifecycle. We wanted to give you a powerful tool for collaboration, that is simple and effective at the same time. Take a look at this bad boy:
The numbers and dots you see are indicators that your topics have something for you to work on. Numbers in squares mean that the exact topic has some unresolved items, while small dots mean that one of the child topics has them.
So, the green stuff is the ToDo items. Each topic has a ToDo list. It’s easy to add items there and track the progress of what’s been done and what’s still left to do. I don’t think I need to explain any further — you all know how ToDo lists work. But having a ToDo list for a piece of documentation, that everyone on your team can see — it’s convenient, eh?
As for review comments, the workflow will seem and feel very familiar — it works pretty much the same way in Google Docs. You select a part of the topic’s content you want to leave a comment to, press Add Comment button (or a keyboard shortcut), and voilà:
You can also reply to other’s comments, resolve or delete them (if you have the permission, of course — that applies to everything). We also added a comment feed for every topic, so now you won’t have to scroll anywhere to see if there are comments. Just click a small button in the toolbar and you’ll see this:
By clicking on the cited content, your view will automatically scroll to the comment’s position and highlight it. Oh, and by default, you will also receive emails about comments with detailed information — who, what, when — the whole deal, you know. And if you want your colleague to see something specific — you can now share direct links to comments.
More agile publishing workflow
Different documentation types require different approaches to their creation and updates. If you’re working on a software that gets a new version once in a while, you’d want to update the whole documentation, making changes to topics that cover features that were tweaked. After you updated everything that was needed, you can publish your whole project, creating a new publication for the new version, while leaving publication for previous version intact.
But when you work with knowledge bases, for example, you might need to update different parts of your documentation and publish them as soon as they are ready. In this update we introduce such functionality — just select a topic you want to publish and you’re good to go:
Search and Navigation
We’ve made some improvements to UI and added some features to enhance your navigation experience.
First of all — we added some visual stuff to help you navigate through your documentation.
You all know and love them. They’ll help you navigate more easily. The good thing is that you can put its code into a topic MasterPage, and breadcrumbs will automatically appear on all of your topics.
Floating self-updating mini-ToC
Yes, now it’s not just a placeable block that you can insert somewhere in your content, but an independent structure with its own fixed position (to the right of the content). And we taught it to self-update, so there is no need to manually edit mini-ToCs anymore. Yay!
As I’ve already mentioned in the sneak-peak, they act as (hash)tags. Assign as many of them as you like to any topic, and that topic will be searchable by those specific words. It will work even if your topic doesn’t have a single notion of a specified keyword in its content. You want your users to find “Update Database” topic by searching “Upgrade”? Easy-peasy with index keywords. But use them wisely and don’t overuse them. They are intended to help you enhance navigation, not to make it more complex. Oh, and keywords can have child keywords, so you can even create an alternate table of contents if you need. Neat, right?
We listened closely to feedback from our users since day one. After all, we’re making a tool for people, right? Full-Text Search improvements are one of the examples of such collaboration.
Overall, search results will be more relevant, as we heavily tweaked some things in our algorithms. We also implemented what you asked us to — wildcard and search operators support. Now you can search for “tab*” if you don’t know whether you want ‘tabbed content support’ or ‘tabletop games’. Search operators allow you to search for “something AND specific OR anything”, among other things.
R E A D A B I L I T Y
It can’t be stressed enough — you’re creating documentation for people to read, not for yourself. Even if it’s internal documentation; one person will write it, but others will read it. And the information has to be easy to understand, logically structured and well-written in general. But how do you measure all this? One person may read the document in a matter of seconds and understand everything, while others will have difficulty wading through complex sentences.
That’s where comes math. Don’t worry — you don’t need to memorize long formulas and count everything manually, we did it for you. When your portal gets upgraded, in every topic you will see something like this:
Those three stats can be customized to show any metric you like. You can choose from a wide variety of them:
There are several complex formula-based readability metrics for calculating readability scores, and a bunch of simpler metrics like word/image count. There’s an info icon next to each readability metric, which will give you a detailed explanation of that metric. There’s no set standard for which score you should adhere to because it depends on the type of documentation you’re writing and your target audience. Read the description and set some baseline for your tech writers. And this info will be right before their eyes — they can see if what they’re writing is too hard for the target audience.
The proud society of ClickHelp’s reports meets a new member — Reader Count report. You’re now able to see the number of unique users who visited your documentation and what they read. So you can finally see if your docs are actually read.
Besides, we’ve improved our report center and reports in general, and they should work much faster.
These are just some of the features and improvements we implemented in this huuuuuuuge update. You can read more in our version history if you’re curious about little details. But I guess I’ll leave you with that.
Oh, and one more thing — we welcome you to try it out yourself. Don’t be shy, the trial is absolutely free for 30 days. It’s plenty of time to figure out whether this is the online documentation tool you’ve been looking for :)
Have a nice day!
Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors