Hacking Author-it Webhelp

Finding the right solution for a problem isn’t always easy but sometimes, if you are very lucky, the solution will fall straight into your lap. Such was the case with our switch to Author-it even though we didn’t fully realise it at the time.

I’ve covered our reasons for switching from FrameMaker to Author-it elsewhere, and once we had converted our content we started to look at how we could get the most from the other output formats available. We already had ideas on how we could use the provided HTML based publishing formats to provide a better solution to the problem of finding information, and we were planning on generate HTML versions of the entire documentation set to be hosted, and searchable, on our community website.

It was right about then that Author-it announced their new ‘Webhelp’ format which would include a (very) quick search in a nice modern looking format. Given that one issue we were addressing was how hard it is to search across multiple PDFs (which presumes the poor reader knows which PDF they should start with) it looked like an excellent solution.

And it is.

We now host a specific build of all of our content within our developer community (which is password protected I’m afraid so you’ll just have to trust me), which allows the developers, partners and customers, to search across everything we have. However we have had to customise the output a little to meet our needs, and this is where the hacking starts.

First things first, the Webhelp output is built using HTML templates (for the layout and structure), CSS (for the styling) and is powered using Javascript. If you are competent in HTML and CSS you can do a lot of tweaking of the templates, although a good place to start is this excellent configuration wizard so generously created by Hamish Blunck.

So what is so special about our Webhelp?

1. Cookie detection
As we publish our webhelp to our developer community website, we want to make sure that only people who are logged in to the website can access the content. So we’ve added some javascript to the webhelp.js file which does just that. The code itself came from our webmaster but it was easy to take it and drop it in. If you aren’t logged in, you get redirected to the login page.

2. Tweaking the look and feel
As I mentioned earlier, after looking at the HTML and CSS myself, I happened across this configuration wizard. It covers most of the basic things most people will be concerned about and after running through the wizard, all I did was change some of the underlying images (to include our logo instead of the “built by Author-it”) and added in a copyright message to the footer. Both of those changes are made in the index.htm template file (around lines 50 to 70). Thankfully the colour scheme of our community website is based around blue so I didn’t have to tweak the colours (Hamish offers some tips on that as well).

3. Google Analytics
Tracking what people are viewing what topics is our ultimate aim. Unfortunately the way the Webhelp system is designed makes that very hard. Without getting into too much detail, whilst there are HTML template files (index.htm which sets the 3-pane view, and topic.htm which styles the topics themselves) the topic content is pulled through some clever javascript before it is displayed. Google Analytics requires a ‘hook’ to be able to track which topic people are looking at and as the javascript method used doesn’t provide that, we are currently blind as to what people are looking at once they get into our webhelp system.

That said, I’ve logged a Support call with Author-it and they are looking at (they are very good that way!). I’m hoping to get a resolution to this as I’d imagine more people might start looking at this area in the future.

4. Automated Build
This isn’t strictly a hack of the Webhelp but I think it’s worth mentioning. Author-it offers a mechanism for publishing via batch file, and we now have a dedicated machine which has a Scheduled Task to run the command line that builds the webhelp. Each Sunday it runs the correct build, and FTPs the files to the webserver. This means we always have the latest documentation available, making it much easier for us to get the information published as soon as possible, removing the constrains of the product release schedules. Whilst working in Author-it, we keep draft information out of the books that will be published until they are complete so there is no danger of the wrong information being published.

And that’s about it.

The published webhelp includes, as the ‘homepage’, a topic that lists all the recent updates the documentation, including links through to the updated topic, but the most impressive thing for the people who use it is the speed of the search. A direct quote from one of our developers, when I showed him how it worked, was “ohhh now THAT’S cool!”, and our Support team are actively pushing customers towards it as well. As making it easy for the technical users to find information was one of the main reasons why we chose this format (and ultimately why we switched to Author-it) I consider that job done.

For now at least.

So, with webhelp published to an area of our community website (it runs in an iframe there, the website itself runs on Joomla), we have an excellent place to direct technical users of our product. The recent updates page also allows me to do a little soft ‘marketing’ in the form of a fortnightly “What’s New” email which I send out to the relevant audience, which helps raise awareness.

The last thing to mention about the webhelp format is that it looks good. That’s one of the instant barriers removed, and everyone who has seen it has said something similar. It looks good, it looks professional and whilst I’m more concerned about the content within it, getting people to like something is sometimes the hardest battle of all. If they like it, they’ll use it and, so far, they are using it in droves.

Update: A quick screenshot of our webhelp based Knowledge Centre.