Tag: Author-it

bookmark_borderTagging

Posted on

Last night on Twitter I asked “Looking for a way to tag topics in an authoring platform. Not part of Author-it, does any app do it?” and a few helpful people gave me suggestions.

I later clarified and thought I’d expand on that here. My clarification was that “Re tagging: we want to tag topics in the authoring tool so whatever the output, the user can filter on tags eg, v1.0/email or v2.3/document”, it was at this point I realised I needed more than 140 characters to explain what I was looking for…

Our product is in the throes of moving to a modular/component delivery. We will no longer have one installer to install one big product with everything in it, instead you will likely (it’s still being figured out) get a core application which you can then enhance with additional modules.

The challenge to our team will be to document this product in a way that is useful to both the people who might use the application and to those people who customise the application for specific customer needs (which may or may not involve customising a module or creating a bespoke module for a customer).

One idea that may help us in this would be the ability to tag all of our content with module/component/functionality tags, and a version tag. There may be more tags required but we can figure those out later.

However, the authoring product we currently have, Author-it, doesn’t offer this functionality. We have looked into a way of manually doing it by hacking XML files but it’s less than ideal.

So what I was asking for, badly, on Twitter was a native application that includes tagging of topics on the authoring side, with the tags then available in the output. Ultimately we want to be able to build dynamic sets of information AND allow the users to change the view of the information based on the tag(s) they’ve chosen as well.

MadCap Flare comes closest as it at least has a notion of ‘tags’ in the product but not sure if that allows a dynamically built output, and Robohelp allows tagging of returned search results but no way of producing that content dynamically.

Does such a product exist? It  feels like it should, that it’s not a million miles away from what a lot of technical writing teams would want… but I don’t think it does. Prove me wrong!

bookmark_borderHow to embed linked images in Word 2010

Posted on

One of the most popular posts on my blog was written a few years ago but still gets a lot of visits and comments; How to embed linked images in Word 2007.

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.

bookmark_borderFurther Webhelp hacking

Posted on

I mentioned in my previous post that we run a webhelp build of our content (a.k.a. our Knowledge Centre) on our developer community website, and that it was hosted in an iframe. I thought it worthwhile fleshing out the detail of that as it includes a bit of custom code some others might find useful.

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.

bookmark_borderHacking Author-it Webhelp

Posted on

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.
Continue reading “Hacking Author-it Webhelp”

bookmark_borderAnalyse this

Posted on

Let me tell you a story. In it our hero (me) fights valiantly against two Javascript dragons called Webhelp and Google Analytics. It’s a bloody battle and at the end, when all the fighting is done, well … you’ll have to read on and find out.

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!

bookmark_borderNumbers game

Posted on

Better documentation lowers support calls, is a widely held assumption and one I’m hoping to prove in the coming months. With our new knowledge centre in place, and Google Analytics tracking how many people are visiting it, I’ll soon have stats for my side of the fence.

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.