Some of the comments have offered better solutions and one in particular I found myself searching for today. Having upgrade to Office 2010 I’ve realised that Microsoft has, again, “improved” the user interface by moving things around!

So, courtesy of Sarah, here are the updated instructions for how to embed linked images in Microsoft Word 2010:

1. With your Word document open, click the File tab, top-left of the window.
2. On the left-hand side, select Info.
3. On the right-hand side, near the bottom, click Edit Links to Files.
4. In the dialog that is displayed, select and highlight the images you want to convert from the list.
5. Check the Save picture in document checkbox.
6. Click the Break Link button.
7. Click OK to confirm.

The links are removed and the images are now embedded in your Word document.

A quick check of the filesize of the Word document should show a marked increase and you can now distribute the Word document, and the Word document only, safe in the knowledge that the images are embedded.

As our content is locked behind a login, we need to be sure that only people who are logged in can access it. This is achieved by a couple of simple checks.

1. When the Knowledge Centre is loaded, a script runs that checks it has been loaded within the correct iFrame within our website. If it’s not, the user is redirected to the login page.

The javascript for this is added to the webhelp.js file (around line 106):

//———– init function ————
Kbase.init = function() {

//OUR redirect
if(window.top.location==window.location) {
window.top.location = ‘URLTOYOURIFRAME’;
}

2. If the Knowledge Centre has been loaded in the correct iFrame (in other words the above javascript is happy), the website checks for a cookie (checking for login) and then either loads the Knowledge Centre, or, again, redirects the user to the login page. The javascript for this is standard cookie checking stuff (google will find you a zillion solutions).

And that’s it. Nothing particularly clever, but a useful way to (lightly) protect the content of our Knowledge Centre.

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.

Some background first.

We have a developer community website which hosts downloads of our software and all the documentation in PDF format. To make it easier for people to find information in the product documentation, we also host a Webhelp version of each and every document in one master Webhelp system so you can search across the entire thing. It works really well.

To track how the other areas of the website are used, we have a Google Analytics account and the necessary code has been added. For the Webhelp, the code is in both the index.htm and topic.htm files.

But, and this is where the story begins, it doesn’t work properly.

Google Analytics will happily track every visit to the WebHelp system, but it stops there. Any click made within the system is recorded as a click but there is no detail on WHAT topic was viewed. We had hoped to get stats on this to allow us to better focus on the areas of the product people were enquiring about but we are, essentially, blind.

It’s very annoying.

Why is this so? Well I think it’s to do with the way WebHelp is created. It uses a Javascript library called Ext JS which, amongst other things, means that every time you open a topic in the Webhelp, it’s loaded through a Javascript call so Google Analytics never ‘sees’ a new HTML page (a new topic) being loaded so doesn’t know what you are viewing.

I think. I’m not 100% sure to be honest.

I’ve logged a somewhat vague Support call with Author-it, and have enlisted the help of our own webmaster. Next step will be to beg and plead with some of the developers for some of their brain power (most of them have a fair bit to spare).

It’s hugely annoying, being so close to what we want but not able to fix it myself, but sometimes you just have to admit defeat.

Of the battle, that is. I WILL win the war!

Early numbers (from the past two weeks) show that more people are looking at the Documentation area of our website than are looking at the Support area, but then the knowledge centre (part of the Documentation area) is new so that’s only to be expected and I’m really not expecting to get a true picture of how things are going until late January next year.

Fingers crossed.

With thanks to Rachel Potts for her post on what web analytics can do for technical communications.