21 June 2011

XMLMind and DocBook

Following on from my recent post about choosing the right tool for the job, I thought I’d share a little of what I’d recently been through doing just that. Imagine, if you will, a software company that doesn't employ a technical author. Most of the time, they write their own documentation (for a fairly technical product set) and bring in someone when major changes are needed, to pull everything back into shape. So far, the majority of the user documentation had been written using FrameMaker - a suitable tool for the job. Unfortunately, there were two big problems:
  1. They were using FrameMaker 7.x, which is not compatible with Windows post-XP (Windows Vista or Windows 7).
  2. You could guarantee when someone wanted to update his or her section of the documentation, someone else was using the 'FrameMaker' machine.

Someone within the company had some experience of using the DocBook schema to write software-related materials, and I was asked to investigate the options available to them to produce all of their documentation in that format. After going through the schema, trying out a few different products myself, and sending links for my client to download trial versions if they so chose, I settled on XMLMind.

Why did I choose this one, and not one of the many other good tools available? Well, it has a reasonably good interface if, like me, you have a preference for the keyboard over the mouse. That doesn't mean you can't use it with a mouse: you can, but I found I soon felt a tad frustrated at so much scrolling and clicking to get to the command I wanted. At the end of the day, as long as the tool selected enforces the DocBook schema so that the same files can be edited in some other way, the tool is irrelevant. I tried that out, moving from one application to another...even dipping into Notepad++ to make sweeping changes.

All that's OK as far as it goes. The one thing that really made the difference, though, was the support. You get access to the support forum, and some of that support is provided by more expert users BUT (and it's a big BUT), your questions are answered promptly and courteously by someone within the company. Not only that, but what really impressed me was that responses were tailored to match the technical content of the question - so newbies like me weren't drowned in technospeak, while the more experienced users got the level of detail they needed. Hussein, take a bow.

13 June 2011

FrameMaker or InDesign?

I’m struggling a bit with user documentation at the moment – from the user side of the fence. It’s not that the information isn’t there – it’s that I seem to be spending a disproportionate amount of time trying to find it.

I’m trying to decide whether I should stay with FrameMaker for a project but upgrade to FrameMaker 9 (as I’m having to run FM 7.2 on a virtual machine in XP mode, and it’s slow) or whether I should switch application to InDesign. I want to find out which option is the least work for me, and for my client who processes the XML output I send.

What’s the problem? Well, I can find a lot of information that is telling me what I can see for myself – for example, that you can ‘Save as’ in XML format – but that doesn’t tell me the steps I need to follow to get a specific output, or even if some things are possible. I’m spending a lot of time on trial-and-error.

I’m also finding that – for some reason – I’m looking for information about InDesign or FrameMaker but am being presented with ‘results’ that, on further inspection, are related to a completely different product!

The forums are a great source of information – user supporting user – but having spent a morning reading posts that looked as if they may answer my questions only to find that they don’t, I’m going to have to ask questions directly that maybe have already been answered.

I don’t know what the answer is... but the experience is making me think about what I write – am I leaving my readers with this same sense of frustration?

A spot of light reading?

I’ve recently completed a short course in writing fiction with the Open University (A174, for anyone who is interested). I found it absolutely fascinating, and a refreshing change from the type of writing I do in my ‘day job’, but I have no desire to become a best-selling novellist, it's not my forte at all.

So why did I take the course? Well, normally, I try to write in as straightforward a way as possible: no surprises, no guesswork, no intrigue. I was interested in exploring the differences, and this course certainly did that. Keeping the reader interested and guessing until the last moment, adding a twist to the tale...things I hadn’t considered since I was at school, were explored, as were building believable characters and plots.

Was it completely irrelevant to technical communication? No, I don't think it was. I found it interesting how different people interpreted the stories I wrote, with the final ‘assignment’ being a particular case in point. The marker commented that one element of the story was improbable “because I had said”...had I? No, I hadn’t – but I hadn’t said what I meant either, and I could quite see how the assumption had been made. Even in the realms of fiction, you can take misdirection and intrigue a step too far.

06 June 2011

The right tool for the job

The array of tools (applications/programs) available to us as technical communicators is vast. It can actually get very confusing at times, with the boundaries between what the different tools can do getting increasingly blurred. We can spend a lot of time working out which ones to use for a particular job – it isn’t always as straightforward as choosing the one designed for the purpose. Compromises have to be made, balancing the needs of the writers/editors, the clients and, of course, the readers.
  • If I choose this one, am I preventing my clients from updating the documentation themselves?
  • Is this one flexible enough to provide outputs in all likely formats, even though my client only wants PDF ‘for now’?
  • Do I know other people with enough expertise in this application to be able to pick up the work if I‘m hit by the flu virus tomorrow?
  • How expensive are the licences for that one? If everyone at my client’s business needs one, does the cost become prohibitive?

After a lot of head-scratching, we make our decision – sometimes trading off a really nifty feature for overall compatability ... but it shouldn’t stop there. If we regularly pick up and use different tools, we will be aware of their uses (and limitations) but we do need to update our knowledge. Making a decision that FrameMaker (for example) is unsuitable to use for a particular project may have been valid for FrameMaker 7, but do the new features in FrameMaker 10 make a difference?

I personally believe that the value and contribution of good technical authors isn’t defined by their skill in a particular tool – or even in several – but in their ability to communicate in a way that their audience can understand and relate to. Having said that, I would expect anyone engaging in a craft for which they are being paid to be at ease with their tools. No matter how gifted the artist, I would expect some understanding of the properties of the different types of paint available, even though the talent lies in producing a breathtaking picture. The sense of awe and wonder wouldn’t last long if the paint all started to run down the canvas as soon as you hung it on your wall!