Category: Work

I’m currently scoping some work to provide a set of user guides for an application. The functionality is, mostly, split into two areas with one set for those administering the system and the other for those who use the system to complete their work.

Previously it would have been a matter of doing some task analysis, which would drive a list of topics, which would then be grouped sensibly, all the while keeping the audience of the information in mind. However, that tends to lead to an exhaustive list of topics, often leading to areas of the product that are little used.

To counteract that one thing I’ll be doing is initially limiting the scope to the production of conceptual information. Whilst some tasks will need a level of procedural steps, I’m more keen to get across the concepts and uses of the various parts of the product.

With this in mind I’m toying with the idea of using scenarios to drive the task analysis, taking the user through a few typical usage patterns and letting them learn the patterns of how the product works. It means that we are going to be relying on the design of our product (which is pretty good) to guide users appropriately through the application.

It’s a bit of a leap of faith, but is it enough? Time will tell!

A few weeks ago Scott, from the always relevant DMN Communications blog asked me if I’d be interested in writing a guest post.

I immediately said yes then, after a short pause, I set the expectation that I wouldn’t be able to write one for a few weeks as I was coming to the end of a project.

So, last week I finished off my guest post and I’m now waiting, somewhat nervously, to see how it will be received. The post goes live on Wednesday, so not long left to find out.

It’s quite liberating, writing a blog post for another website (not done that for years), and it sparked a few ideas for this place as well. You’ll start to see some of those soon.

Thanks to Scott for the opportunity, and keep your eyes peeled to the DMN Communications blog on Wednesday.

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!

Before I say anything on this topic I’ll confess that I am not fully versed in the history of the organisation. I am not a member, this is merely my take on some of the blog posts I’ve read on this matter.

And there in is the my main point.

I’ve read a lot about the issues the STC are currently facing but have yet to read anything from the STC itself. No doubt there is an STC mailing list ablaze with such news but given the amount of negative press currently floating about on blogs and on Twitter I’ve yet to spy any sort of formal, or informal, word from the STC.

I’ll let you read into that what you will.

Elsewhere there are plenty of suggestions to solve the initial woes, and many ideas of how to help the STC modernise and become the organisation the members want and, as I’m not a member, I can allow myself to suggest that perhaps the time has come to wrapup the STC and let a new organisation grow from the ashes.

Those who are interested, and who believe our profession needs such an organisation will rally round and rebuild something. If there is not enough interest then perhaps that is a further indication that the STC has had its time.

I’m not suggesting that technical writers do not need an organisation like the STC, there are many many good benefits, and I’m fully aware there is a lot of history and hard work that has gone into creating and building the STC. But sometimes it’s better to cut your losses.

Of course, a large part of me hopes that it won’t come to that.

But I must admit, part of me is intrigued to see what would happen if it did.

I’m guessing that you don’t want to miss that landing pad because if you do you’ll end up ditched in the ocean, floating around aimlessly and with no real idea of what to do next. Can you imagine how horrifying it would be if that happened? Floating there, unable to get back to land and with who knows what swimming around underneath you…

Yet this is the predicament that many users of online help find themselves in, having strayed into the online help they have been cast into an ocean of information with no real idea of how to get back to shore. Ohhh sure, we tell ourselves that the there is an easy way to get to the information they want through our carefully crafted Table of Contents, or perhaps a more direct route can be navigated using that Index you toiled over for hours, or better yet if they use the Search functionality they’ll find what they want. Right?

And, ultimately, yes these mechanisms work. If you know how an Index is structured you can quite quickly navigate to a keyword that probably matches the information you are searching for and should, hopefully, take you almost directly to the very help topic you need. Same goes for the Table of Contents although they are a little more prescriptive and you need to know what you are looking for to be able to find it, and of course the Search will provide you with several help topics that are, probably, what you are looking for.

Meanwhile the sharks have gathered and are nibbling at your feet!

At the UA conference last year, Matthew Ellison gave a presentation on what he termed “Keystone Topics” and in the Summer edition of the ISTC Communicator magazine (again, chock full of good stuff, it’s worth the price of membership alone if you ask me) Paul Filby covers something similar, outlining how to provide “The perfect help-system landing page”.

And so, with all of that in mind that is my task today (yes, a Saturday).

The concept is simple enough. You create a single topic that will be displayed to the user when they bash our old friend the F1 button. That topic is unique to the help system and, based on context, can be used to display a smarter set of links to potentially useful information. If you have the means you could display the most commonly viewed topics or, as I’m doing, you can point to the start of several paths covering the most commonly used areas of the product.

I don’t expect to get ours right the first time round, but hopefully the concept will work. I’m including a small addition to the foot of each such topic, asking users to contact us if they have improvements. It’s only on the landing pages but I’m hoping it might drive a nice little cycle of innovation with direct feedback from the users driving the content of the landing pages in the future.

Hopefully the landing pages will give our users some where dry to stand and survey the land a little, with clear signs to help them get to where they want to go.