For version 5.3, Author-it released new web help templates and having played with them a bit I have to say I like them. However I was struggling to see how to enable some of the options that you can see in the example Author-it provide, so off into the HTML and CSS files I headed to see if I could see anything useful in there.

And there is, several of the options are commented out in the HTML code and with a little bit of poking and prodding I got some of them to work. Pretty straightforward, if you know HTML and CSS that is.

But what if you don’t?

Well the good news is that the ever productive Hamish Blunck has created an Author-it Web Help Configuration Wizard which, in a few simple steps, will produce you a custom Web Help template. It really is very simple and works like a charm, it also uncovered a few options I hadn’t spotted in the code.

Thanks to Hamish for providing this to the Author-it community (he also hosts a search engine that polls the old Yahoo Group). Great stuff this, go and give it a shot.

The following are not in any particular order. Some are tips gleaned from experience, some are links to the knowledge being shared by others, all have helped us get us from a standing start to a full content conversion and production delivery in under 4 months. We started with ~2450 topics of imported content, and managed to keep pace with the development team as well as cleanup and backfill the imported content. Quite a feat!

Working with Author-it

As we were converting a LOT of content from FrameMaker to Author-it, there was a LOT of cleanup required. Being able to customise the styles toolbar, adding in the most common used paragraph styles for example, was a huge bonus. We ended up creating one under the Supervisor login, and then each team member copied that to their installation.

Apparently Prompt for unsaved changes is turned off by default. We found this out the hard way, so click the big Author-it A and check in the options to turn this on.

JavaHelp Tips

JavaHelp uses the HTML templates, so if you provide customised HTML templates it will use those.

This next one might be specific to the way our development kit works.

To get context senstive help working you need to add the agreed string to the Context String field on the Help tab of the Topic Properties dialog.

We used this on some topics that will only appear in the help system, allowing us to create ‘landing pages’ which can then direct users to the most pertinent topics for the area of the product they were using when they launched the online help.

MiniTOC

These are, by default, used in Chapter templates. To get better control of the layout of these (our issues were mainly with vertical white space, or lack thereof) we decided to not have any content in a Chapter topic. That way it is only used to hold/generate the MiniTOC and the next topic holds the first block of text for the chapter.

Terminology

To make it easier to reuse topics anywhere, we switched our terminology slightly. There is no such thing as a chapter anymore, unless you have Word/PDF specific topics. We use ‘section’ instead.

Word template

The source of many a frustration, but that’s not really the fault of Author-it.

One thing I’d suggest you do first would be to figure out what macros you need and get them into the template first. Remember to configure the Publishing engine to use them as well.

We are using the following macros, all of which are available from the Author-it Yahoo Group:

• HyperlinkedTOC – creates links from the table of contents text, rather than just the page numbers
• RemoveCH – Removes the CH from the SuperHeading text
• ResizePictures – makes sure images fit the column width
• ResizeTables – make sure tables fit the column width
• SaveAsPDF – creates a PDF of the Word document

See how to Add an Author-it AfterPublish macro to the Word template for a simple set of instructions.

Problems with numbering? Julie Goodwin, Technical Support Team Leader at Author-it, popped up in a comment last month and pointed me at this solution.

Useful links

First place to head for information is, unsurprisingly, the Author-it Knowledge Center, it’s a replication of the entire documentation set plus some very useful Tips and Tricks and Workarounds.

After that, your next step should be the Author-it Yahoo Group. It’s active and full of hugely helpful and knowledgeable people and without their help I don’t think we’d have managed to hit our project deadline.

One member of the Yahoo Group, Rhonda Bracey, has published several excellent tips on her blog. Well worth a look.

A recent addition to Author-it, one we are currently looking at, are Variants. Hamish Blunck has an excellent overview of how Variants work, and there are more goodies to be found on his website.

And last, but not least, there is an official Author-it Blog which publishes product news, tips and tricks and other random stuff on a regular basis.

As we approach the end of our migration from FrameMaker 7 to Author-it, I’m going to try and pull together some lessons learned, some tips, and useful links that I’ve found along the way. I’m not claiming to be an expert (I’ll leave that to Rhonda Bracey and Char James Tanny, amongst others!) but, as they say, a problem shared is a problem that you might just find via a Google search… or something like that…

Pre-empting this, I thought I’d open things up to anyone who might have any questions about the process we’ve gone through. So, if you want to know my thoughts on migrating content (how NOT to do it, perhaps?) or anything specific to Author-it then leave me a comment.

Over to you!

When I get to the bottom
I go back to the top of the slide
Where I stop and turn
and I go for a ride
Till I get to the bottom and I see you again!!!!

Ever get that feeling that you’ve been here before?

I write this blog post with haste as I’m halfway through the penultimate week of a particularly arduous project. Not only are we releasing a new version of the product, but we are completing the first major stage of our move to Author-it.

Overall the migration has been pretty painless. There are still some Word templates issues to work around and getting to grips with Variants has still to be tackled, but overall we are pretty happy with our choice. The only major gripe we have is partly our (ok, MY) own fault, and it’s here that I’ll offer the most valuable tip I can.

If you are migrating legacy content to Author-it (we were moving from Structured FrameMaker), make sure you thoroughly test and check the import settings. Time constraints had me rush this stage and we ended up paying for it, spending far too long cleaning up rogue topics than we had planned. Every cloud has a silver lining though, and it does mean that the documentation is now far more consistently written and styled than it had been. However, going through some 5000 odd topics by hand wasn’t the greatest use of our time!

Soon we will be looking to how we can leverage the output to provide better access to information, feeding into the developer community website we have already built, and improving how we deliver information alongwith our product set.

For the former we have taken some inspiration from the presentation by Rachel Potts and Brian Harris (Red Gate Software) at last years UA Conference, titled Delivering Help in a Support Portal. For our implementation the Publications team will take the lead, and it’ll be interesting to see where it takes us. Web 2.0, anyone?

We will also be looking to provide better online help by introducing Keystone Topics, as suggested by Matthew Ellison. Author-it should make these topics, which are the first topics the user lands on when they start the online help and which provide sensible links to common information (rather than just providing repurposed user manuals), very easy to build.

Two of the team will be in Cardiff for the conference this year so it’ll be interesting to see what we learn there and how we can really start to leverage Author-it in more and more powerful ways. I’m definitely keen to start innovating what we do and, in a few weeks time, we won’t have any further barriers to stop us.

Firstly a quick thank you to everyone who has commented on the previous post. What a fantastic bunch you are, and as I mentioned in the comments, I’ll be using your first names and locations in an infographic for an upcoming presentation. Fame will be yours! (Note: fame not guaranteed)

In other news I’m deep in the trenches of 2000+ Author-it Topics, stepping through each one to clean up formatting, correct hyperlinks, set the correct template and so on. I’m working my way through all our old content, imported using the MIF Import. It’s not the most stimulating work but needs must.

On the way I’m fixing bits and bobs in both Author-it and the Word template that we’ll use to generate the PDFs of our documentation from. If nothing else the context switch is keeping me sane!

One annoyance is the fact that I’ve had to add a “Reset Numbering” paragraph style as without it you’ll find your numbered lists (that we use for procedures) roll on and on through your document. I’d have thought the Procedure Heading style would’ve been setup to handle this out of the box but, alas, not. So far it’s the weakest area for me, and I’d certainly love to see some more example templates, either provided by the company, or on a community submission basis.

I’ve also spent a fair bit of time dipping in and out of the Author-it Yahoo Group which is a fantastically helpful resource. Well worth joining if you are an Author-it user.

Right, best get back to it. Hoping to get that number below 2000 by the end of this week!

Using Author-it to produce Word documents is easy. The tricky bit is distributing them.

Without running any post publishing macros, the Word document that is generated will be using linked images. So everytime you need to distribute the document you’ll also need to remember to include the images as well.

I frequently forget this, hence why I’m posting this, so, if all else fails, I can at least search my own blog to find the solution. If you look at a document with linked images, you’ll see that the filesize for the document is quite small, and there will be a number of images in the same folder (although this works fine if your images are linked from another folder).

UPDATE: You can also do this automatically after publishing using an afterPublish Word macro, the Author-it Knowledge Centre has the details, thanks to Derek Tomes for pointing it out. Read on for the manual method.

You can quickly and easily convert linked images to embedded images in Word 2007. Here’s how:

1. With your Word document open, click the Office button*, top-left of the window.
2. Select Prepare > Edit Links to Files.
3. Select and highlight the images you want to convert from the list.
4. Select the option to Save picture in document.
5. Click the Break Link button.
6. Click Yes 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.

One part of the agenda for our day long “Author-it day” was to consider how we would handle multiple streams (versions) of documentation.

As well as major versions of the documents (3.x) that continue to move forward, we also keep up with changes to maintenance releases (3.x.x). The overhead isn’t too bad, we rarely have to make changes for a maintenance release, but we do need to have the capability to do so and this is where we hit a stumbling block.

Author-it offers the ability to version an object (a book or topic for example). You can have multiple versions of an object but only one can be active. So, originally, our thinking was to create the first (in Author-it) version of each Book and then use the basic “1-up” versioning provided by Author-it.

However, when running through a quick demo of such a system, it became apparent that whilst that model works for major releases (X.x) when you consider the occasional maintenance release (X.x.x) then, very soon, your folders become cluttered with a myriad of versions of objects, none of which are easily identifiable to a particular product version.

So, our solution will be to duplicate objects (copy) to a new version specific folder.

We are switching to Author-it just in time for a new major version of the product line. This allows us to import ALL our existing content as 3.0. From that point onwards each major version will kick off with the duplication of all the Book objects (remember, a book is just a collation of topics for output). Then any topics that change, or are added, for that version will be duplicated (copied) and moved to the new version folder.

Clunky? A little. Manual? Completely. But it’s the only way we can manage our versioning process without ending up with a mess of versioned objects.

Unless, of course, we’ve missed something very obvious.