Tag: <span>HTML</span>

I’m procrastinating.

I’ve reached a certain point in the work I’m doing that requires the completion of a very large planning spreadsheet. I’m currently looking at all of our content with a view to restructuring it to fit better with the way our customers work hopefully making it easier for people to browse the content.

I’m taking an organic approach for this first pass. Taking the chapters in each current guide and rather than forcing them into a pre-existing structure, I’m making an educated guess as to where they might live in the future. Once that is complete I’ll take the list of suggested locations, give them a quick sanity check and mockup some examples and take them to some of our customers.

This is all part of a move away from monolithic PDFs, towards a more focussed set of content that is available online. However, whilst we are concentrating the bulk of our thoughts and efforts on our HTML based “Knowledge Centre”, the need for PDFs remains and hopefully the new structure will help keep the set of published PDFs much leaner by splitting out only the information that people need to be published in that format.

At present it’s definitely one of those jobs that ‘just needs done’. It’s not hugely challenging, nor particularly enjoyable but such is life. The end goal will, hopefully, just the means and all that.

It’s still got a way to go before it best my ‘most boring job’ though. That one involved reformatting hundreds of single pages of content, all held in separate Word documents as part of a migration process from one tool to another. It only took a month or so…

Work

Comments closed

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.

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!

Work

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.

Comments closed

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase.

It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies.

Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online).

So why do we still maintain this view of how information should be provided?

There is a level of comfort in having a table of contents and a structure to the information available when writing technical information. It allows you to make sure all the required information is in place, but most of the research I’ve read, and most of the anecdotal evidence I’ve heard, suggests that those lovingly created table of contents are not heavily used.

The index is another area, hell it’s another profession altogether, that we spend a lot of time crafting and rightly so as it is used by many people to navigate their way through a document.

But one thing that trumps both of these methods isn’t available in printed documents but is widely available for online information. Search.

OK, so none of what I’m saying is new, or revolutionary, far from it. Those of us who have been creating online help, regardless of the format (a lot of which was before the internet was popularised), know that if there is a search option available, it will be used.

With that in mind, and this is most definitely something we will be consulting with our users about, we are toying with the idea of dumping the index and the table of contents, making sure the content has a good set of internal reference links so users (power and novice alike) can find “paths” through the information, and switching the front page to be a Google-esque search.

Luckily we can pilot this approach whilst still producing the Javahelp, PDFs and HTML (Webhelp in Author-it terms) output so we don’t completely alienate our users. It’ll be interesting to see outcome.

Work

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.

Comments closed

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.

I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

Why? – why single source?

A quick summary of our current situation. We currently maintain (and add to) ~2000 pages of documentation. The same content is used for both the PDF manuals and the online help provided with the product (exactly the same, no restructuring). There are various levels of coverage (some good, some bad), we are embedded within an Agile development environment, limited publications resource. On top of that we have an aggressive release schedule and a two-tier product which includes a development kit and an application built by us using that development kit.

Whilst we have made good strides in improving how we work with the software developers – we have a technical writer embedded in each new feature team and the benefits are evident from both sides – we know we need to be focussing our efforts in the correct areas, and providing information in a structure and format that meets the needs of our audience. Luckily we have direct access to the largest section of the audience as they work for the company.

Better structured information is one of the requests, and to allow us to get the most of our current documentation we would need to reuse a lot of the content we have already, but it’s locked away in FrameMaker files, sometimes in the depths of a 100 page long chapter. What to do?

Ultimately we believe that the ability to reuse our content will make producing the content faster – the current documentation set is unwieldy and hard to search, a little digging reveals some duplication already exists – and make us much more flexible when it comes to providing useful sets of information for our audience/customer.

Eagle-eyed readers will have spotted that we already single source our documentation and online help from the same FrameMaker files, but as we don’t reconstruct the online help into something more intuitive and useful it is, essentially, an HTML rendition of the manual. Not ideal by any stretch of the imagination.

Comments closed