bookmark_borderAccess is good

Access

Yesterday we launched a new version of our developer community website. It doesn’t have many ‘community’ features as yet but that’s all to come. One thing it does now have is an HTML version of all of our product documentation, in an easily searchable format.

It’s no coincidence that it looks very much like the Author-it Knowledge Center as it too was built using Author-it (alas I can’t show you our website as it requires a login).

This new format of the product documentation is largely to move us away from PDF only documentation. At present we still have a set of PDFs but they aren’t particularly usable.

We ran a few quiet trials of the knowledge centre format and everyone who saw it liked it, particularly the fact you can search across every piece of information offered.

So I was definitely pleased when, after sending out a company-wide announcement about the new version of the website, highlighting some of the new features, one of the first pieces of feedback I received was about the knowledge centre and how good it was. For the, as the kids say, win!

The knowledge centre will be updated on a regular basis, so my next challenge is to figure out a way to embed RSS notifications for new/updated topics. But so far so good, and with Google Analytics in place in the knowledge centre, we can continue to make improvements to both the information itself and in making sure it is accessible.

It’ll be interesting to see how the knowledge centre is used, particularly if we manage to track it against the number of incoming support calls as the main reason we are adopting this format of information is because, many times, the answers are there, they just weren’t that easy to find.

bookmark_borderAuthor-it & Word

A teeny tiny gotcha that I thought I’d mention here. I can’t find explicit mention of it in the Author-it Knowledge Center and it’s tripped me up a bit.

Quite simply, and I realise these will sound obvious, make sure everyone who is using Author-it is using the same version of Microsoft Word.

My particular scenario has my laptop running Word 2007, making changes to the template, but when publishing from a machine running Word 2003, the footers weren’t being displayed despite the AutoText entry being available in the output Word document.

Naturally I’m discovering this delightful quirk on the final day of the project as we do a final publish and check on our deliverables. And people wonder why I’m almost bald…

bookmark_borderAuthor-it Web Help Configuration Wizard

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.

bookmark_borderAuthor-it Hints, Tips, & Useful Info

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.

bookmark_borderComing soon…

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!

bookmark_borderHelter Skelter

Helter Skelter

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.