bookmark_borderTCUK10 – quick guide

This is an update to a previously published post.

Not all of the sessions are scheduled yet, so I’ll update this as and when but, if you are wanting a quick print out of the session to, for example, convince your boss to splash some cash, then hopefully this PDF will do the trick:
Technical Communications Conference 2010.

(Note: a similar PDF is also available from the conference website but I think mine is prettier :p)

bookmark_borderRemembering the basics

What do you call your documents? What is the first thing you do when you start writing? What is the last?

All these things that you do without thinking about, the basic automation that your brain easily handles, over and over again, these things are, to you, so basic as to be forgettable. You don’t tell anyone else to do them (they must know, right?) and you probably don’t remember where you learned how to do them.

You bulid your own mental checklist and that takes care of that.

Need to provide a PDF of a document for someone? No problem, generate it this way, name it in this manner to keep it sensible and consistent and put it THERE (as you know everyone has access to it that way). And so on and so forth. All these things locked away in your head.

That mental checklist is made up of many things, from coping other people, reading books, and learned from mistakes. Without it you’d be lost, and with it you retain value as you are the person who knows how to do those things.

But that also means you are the bottleneck, the only person who knows X and Y, and can help with Z.

Better to share that information, let others learn and improve it (and they will). It allows them to do more, and lets you do other things. More power to the team, and a better service to the rest of the company, further cementing the value you bring to your organisation.

bookmark_borderAnalyse this

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_borderTechnical Documentation Know-how

A few days ago I received an email about a new website. I’ve seen it mentioned on other blogs but think it’s worth repeating as there is some useful information there.

I am contacting you because I have just thought that maybe a post about my new web site on software documentation and user assistance could also be interesting for your readers. In addition to about 250 useful links for technical writers, the site for example provides checklists and up-to-date market surveys of more than 350 help authoring tools, screen capture tools, screencasting tools and other utilities for technical communicators. All information can also be downloaded as a PDF booklet (approx. 100 pages).

On the website you can find some basic know-how, checklists, tools and links, which will help you to create clear and concise user-friendly manuals, online help files, software demos, tutorials and other forms of user assistance. Go have a look.

Thanks to Marc Achtelig of indoition for getting in touch.

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_borderDumping the manual

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.