Technical Communication UK 2011 (Day 1)

I thoroughly enjoyed my first day at Technical Communication UK 2011. Tuesday is ‘workshops day’, and I was spoilt for choice. After much deliberation, I finally settled on ‘Intuitive images: tips and techniques for creating and evaluating graphics in your products’ with Patrick Hofmann and ‘Can CAD destroy the art of technical illustration?’ with three (very patient) people from Altran Xype. (To see everything that was available, go to the Programme page on the website. Links to presentations and videos of some of the sessions will gradually be posted there, too.)

Patrick’s workshop managed to be entertaining and thought-provoking at the same time. We all puzzled over some of the symbols, and it dawned on some of us that something ‘obvious’ is not necessarily representative – and may not make sense to a large percentage of the global population. Depending on the work that we do, some technical communicators may have little involvement with icons and symbols in that sense, but Patrick’s workshop covered other image-based communication, including flowcharts. I’ve come away with a lot of ideas (and, I’m pleased to say, some nice warm feelings that I’m getting at least some of it right).

The afternoon session was very different. Altran Xype have a product (3DVia Composer) that – if I understood correctly – enables technical communicators to make use of available CAD data to create the types of illustrations and animations that are needed when trying to explain or instruct. Workshop attendees were given a copy of the software prior to the event, so we could load it onto our laptops, and we spent at least half of the session trying it out.

I’m not a technical illustrator, and primarily document software – but there are times when something like this would be invaluable. How much better to be able to create the step-by-step diagrams myself, showing exactly what I need to be able to show, instead of relying on a flat image exported from a CAD system that isn’t at the right angle or that doesn’t show the detail that I’m describing. I’m certainly going to share information about this product with my customers, as I can see many uses for it in engineering and manufacturing.

As always, a huge part of TCUK is the calibre of the delegates – so many people to talk to, and so little time! The conversations over lunch, dinner, in the exhibition area and any time you find yourself sitting or standing next to someone make it fantastic. The only three days in the year when I can have a professional conversation with someone without having to try to explain what I do first!

Getting started: step 1, what are you writing about?

I'm sometimes asked what the first steps are in writing ‘good’ documentation... where to start. My answer is usually that you need to have clear answers to four vital questions... what you are writing about, who is going to read it, why are you writing it and why are your readers reading it.

These are only a starting point, and I’m going to take each one in turn, although you need to combine the answers to them all and not act on one in isolation.

First, what you’re writing about. People often think this is the ‘obvious’ question. There’s the software/product/service – just write about it!

But I believe you need to dig a little deeper. Some topics are so huge that you need to narrow down the scope or you’ll drown in information. Others so diverse that you could be looking at it from a completely different perspective to the person who’s asked you to do the work.

Imagine that you are asked to write about the way a company documents its products(a common enough scenario). You could look at this in a number of different ways:

• The documents that accompany each product (user guides, reference manuals, tutorials, training materials, online help) and guidance on what goes in each.
• The applications and tools that are used for the various types of document - and possibly instructions on their use or the methods that have been adopted.
• Typographical, stylistic, naming and other conventions, helping writers to conform to the brand identity of the organization.
• The review process, and how updates are handled.
• Language guides to aid translation or understanding by non-native speakers.

And these are just a few that have occured to me while writing this!

So when someone asks me to ‘write about X’ something, one of my first questions is always to find out ‘What about X?’

Next, we'll look at step 2 – who is going to be reading it?

Twitter – is it just me?

I’m still struggling to work out the point of Twitter – what it’s giving me that I’m not already getting elsewhere, and in a much more useful way. I acknowledge that it ‘works’ – that information flies around the world as an event is happening. I also understand that it raises the profile of people, products and organizations as well. I’m not arguing with the statistics.

My struggle to engage is on a more emotional level – and I’m sure I’m not the only one. I feel as if I’m in one of those TV game shows where the host reveals a picture a bit at a time and the contestants have to try to work out what it is. Too much of it is still covered up for me to have a clear idea. So my question is... what am I missing?

I revisited my Twitter account this afternoon, fully intending to tweet something. Anything would do, because in all the time I’ve been able to, I’ve sent the grand total of 15 tweets. This wouldn’t be a large number if I’d started last week – but I started in August 2009, feeling that I really ought to do this, as a technical author who writes about (and teaches) technology!

Before diving in, I thought first I’d better find out what others were saying, so I spent a bit of time glancing through the recent tweets from a few of those I follow. For the most part, I didn’t have a clue what they were talking about. Many were obviously responses to earlier stuff, but there’s a limit to how much effort I’m going to put into catching up. Some had links to blog posts and websites. I followed one or two – those that were clearly labelled and I had an idea that I’d be interested when I got there. (This is about the only use of Twitter that I ‘get’, but even then, I’m sure I miss some gems because they are buried so deeply.)

Perhaps my problem is that I don’t get the tweets to my phone. I tried it for a while, but it drove me mad. Nothing urgent will ever be sent to me via Twitter, and it’s difficult enough dealing with the text messages and emails, without adding Twitter to the mix.

Did I tweet? No... couldn’t think of a single thing I wanted to say.

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.