27 October 2011

Winning a documentation award

I’ve been a member of the ISTC for quite a few years now, and have been ‘aware’ of the award scheme but had never managed to enter it before (for various reasons).

I was absolutely delighted this year to find that I’d won the Instructional Class at my first attempt. Yippeee!

26 October 2011

tcworld at Wiesbaden - October 2011

I arrived back home after midnight on Thursday night/Friday morning after an exhausting – but very enjoyable – three days manning a stand at tcworld in Wiesbaden, Germany. I was there, with a colleague, representing my own professional organisation (the ISTC) among associations from many other countries.

We were busy – so much so that I only managed to attend one session (and now know a little more about HTML5 as a result). We (the ISTC) don’t attend every year, so it was interesting to see what had had changed since our last visit in 2009.

As always, the size of the exhibition at the event was huge – filling three large halls. I recognised some from TCUK (Technical Communication UK), the conference hosted by the ISTC. Many, though, were completely new to me. As you would expect in a location in the heart of Europe, surrounded by countries speaking other languages, translation and localisation companies made up a significant proportion of them.

The gratifying change was that our association is becoming recognised – mainly as a result of our success with our conference and through our flagship publication, Communicator.

The sheer numbers meant that the sense of community didn’t seem as strong as at our own more intimate conference, but I did meet – and have some meaningful conversations with – some very interesting people. A signifcant number of the presentations (about a third) were in English, and I believe that is normal for this conference. If you are able to attend, even for just one day, it would be worth it.

Sometimes I feel I’m very much in a minority profession; attending an event like this makes me realise just how many technical communicators there are.

25 October 2011

Technical Communication UK 2011 (Day 3)

I spent most of the final day in the ‘Anything but text’ stream, with the only exception being the first session of the day.

I began the final day of the conference by attending Zsuzsa Nagy's session (‘The ups and downs for using a wiki for tech pubs guidelines’) as I had suggested a wiki to a current client to meet their requirements for content that was centrally stored and easily updated... and I had promised to investigate further at the conference. Zsuzsa’s session answered the majority of my questions, and I found some of the hints and tips she gave for keeping the content up to date very useful.

Zsuzsa’s company uses twiki, an open source wiki that is easily customisable. They add a few bits of information to every page: the owner of the page (so someone had responsibility for ensuring the content was current) and the date when the content was last reviewed. Last reviewed was felt to be more useful than last changed, as a review may result in no changes to the content if it is still accurate – but it was felt people were more confident to use the content if they could see it had been checked relatively recently.

I followed Zsuzsa’s session with one given by someone who feels like an old friend. Ron Blicq ran a short workshop at the very first ISTC conference I attended, and I remember sitting with him at lunchtime on that day and feeling very much at ease. Ron’s presentation this time was particularly inspiring for me, as he had used his communication skills to reach a very special audience: people with learning difficulties and their parents. I was impressed both with the way Ron had approached the task, presenting the information as a series of short plays, and the way in which the scripts were so true to life. I believe Ron is writing an article about this project for the Winter 2011 edition of Communicator – and even though I was at the presentation, I will read it with great interest.

Staying with the non-text theme, Matt Pierce from TechSmith gave us some ideas on screen captures using Snag-It (a favourite tool of mine) – and in return, I mentioned to him some of the little niggles I have with the program.

Afer lunch, Matthew Ellison’s session (‘Speak out! Narrate your way to success’) helped those of us who occasionally have to provide audio to accompany our software simulations to do so with more confidence. One piece of information from Matthew really stuck in my mind – and was useful just a few days later. He said to try to record as much audio as you could in one go, and if you needed to have a second (or third) session to try to do the recording at the same time of day. I had noticed that I sometimes sounded different when playing back audio to tidy it up, but hadn’t realised until Matthew said that the time of day (and how much I had been using my voice) was one of the things causing the difference.

The popular questions and rants session from the previous year was repeated, with a number of participants each being allocated three minutes to have their say. I had a question/rant myself... why do Adobe products (Captivate and FrameMaker are the two that mainly affect me) make it impossible to make changes to a file created in an older version without upgrading the format to the new version?

The closing keynote was given by Ellis Pratt – thank you, Ellis, for stepping in at virtually the last minute. A very interesting talk, which rounded the three days off nicely, giving us plenty to think about as we found our way home.

17 October 2011

Technical Communication UK 2011 (Day 2)

I know there’s been a bit of a gap between Day 1 and this post – but I’ve been playing catch-up for a while. Writing down what I did and what I learnt is useful for me anyway, so I’m going to get on with it before I forget.

There was so much choice that I struggled to decide what to attend. I’m a lone technical author and although I could end up working in a very structured-authoring way, I haven’t been in that environment since going freelance nearly 7 years ago. (Maybe my contracting colleagues who work full-time on projects for a number of months have more exposure, but my work tends to be shorter, more discrete pieces of work.) Based on this – and as I am extremely interested in the layout and appearance of documentation to help understanding – I found myself concentrating on the the specialist stream: ‘Anything But Text’.

The day started with a thought-provoking keynote from Patrick Hofmann, entitled Make icons make sense: solving symbols for global audineces. I’d attended his workshop the day before, and so did wonder if it would be ‘more of the same’. It was and it wasn’t. The day before we had looked at providing visual information for a very defined group of people, who shared a lot of characteristics (culture, language, previous exposure to the subject). Today we looked at how people you might on the surface consider to be fairly homogenous could actually be wildly different. This fitted in nicely with a lot of things I’ve been thinking and reading about lately. As technical communicators, we often have strong ideas of how different ‘cultures’ view different things. These ideas may even be based on research – which is great. But do we take into account how those ‘cultures’ are evolving? Is the culture of young people in a country the same as that of the older people? What about city dwellers compared to those in a rural environment? It seems to me sometimes that there’s a lot of guesswork going on... and that in trying to accommodate, we sometimes (unintentionally) confuse. For example, I know that Chinese family names are traditionally first, then the personal name. I’m not familiar with all Chinese names, though, so don’t recognise from the sound which is which – and have before been told a name that has been reversed because the speaker knows that in my culture we put the personal name first.

Next, I went to the colour workshop with Greg Urban (Rules of thumb for using color in your content). That was absolutely fascinating, and Greg handed out colour wheels that we could use to follow the theory. Unfortunately, I took mine out of my bag to show to someone and lost it... I will have to see if I can get another, as it was extremely useful.

Forms are another of my pet annoyances (see a much earlier posting in this blog). Perversely, I quite enjoy filling out forms – well-designed ones, that is. I hate forms that don’t have enough room. I hate forms where I don’t know what they want me to do ("Do they mean have I ever done this before, or are they only interested if this is the reason I’m contacting them?"). I hate forms that look as if they’ve been designed by someone on their first day of a ‘Let’s learn Word’ course. So, with this baggage, I decided that Robert Hempsall and Caroline Jarrett may have some insights I could use in their session: Who enjoys filling out an application for a driving licence. One of the most interactive sessions of the conference, we all got the opportunity to start filling in an application form for a UK driving licence – and critique it. One of the big things I took away was from a stupid mistake I made... one of the questions asked for my address when the previous licence was issued. As soon as I saw the blank look on Caroline’s face, I realised I’d interpreted the question wrongly – or at least, got my terminology wrong. A licence is ‘issued’ every time you change address – it isn’t when you move from one category of driving level to another (provisional to car to car + motorbike) which is what my brain had decided it was. I had interpreted the first time I got my full licence as that being an ‘issue’, and subsequent ones being ‘copies’ or ‘replacements’. Hmm.... daft mistake, yes. But maybe I’m not the only one to misread a form?

After lunch I went to see Andrew Lightheart. Andrew had been sat by me for dinner the previous evening, and I’d already decided he was someone I must go to listen to. Easy to talk to, and to listen to, I just had a good feeling about it. Nothing ground-breaking for me, but a few good hints and tips that I have since used – mainly around not letting the audience’s questions side-track me away from the main point of the presentation I’m giving. Kai Weber has written a great summary on his blog.

I switched streams mid-afternoon and went to see what I could learn about eBooks, as I have a client who is considering moving their publications in that direction. In fairness, the title did include the words ‘in technical communication’, and my client’s publications aren’t in that field, but even so I came away feeling disappointed that I hadn’t learnt anything I could apply.

Finally we closed with another keynote, this time from Ikea. Love or hate the instructions, you have to admire how much they have achieved when you realise just how many languages they have to deal with, and how many different national regulations on the inclusion of instructions they have to comply with. Of particular interest was an instance where a national regulation – designed to help – actually hindered. The documentation people at Ikea had what I thought was a very good idea. They recognised that many countries have large communities that speak other languages to that country’s national language. They thought it would be a good idea to be able to ask the individual customer which language they would like the instructions in, and to print a copy there and then. Fantastic! But it couldn’t be done. Why? Because the regulations stated that the instructions had to be IN the box with everything else... and although printing in anyone of 50+ languages (can’t remember the number – may be more, may be less) on demand is one thing, printing 50+ copies per box is something else.

05 October 2011

Customer service? When will they ever learn...

I recently tried a service, offered by someone who knocked on my door one day, that meant my wheelie bin was disinfected after it had been emptied. The basic job was OK, but the fact I had to up-end it to drain the fluid left inside meant I ended up with more work, not less. What has this got to do with technical communication, you say?

Well, the reply I got to my (if I say so myself) polite message expaining that I no longer needed their services was rude, to say the least. Not only rude, it was full of spelling and grammatical errors – not that a perfect command of written English is a required skill for wheelie bin cleaning, I admit. The errors I could ignore...but the tone I couldn’t.

I have no idea whether the man replying to me intended to be as offensive as he was – although a subsequent message leaves me to believe he did – but that was certainly his effect.

Does it matter? Maybe, maybe not. It depends how many people read the review I’ve posted on Yell before engaging his services. It depends on whether he decides to advertise on the local directory services, which also provide the facility to leave reviews. It depends on whether any of my neighbours who were also approached about the service but declined ask us how we found it.

He could have said the same things in a much more pleasant way. A way that would have encouraged me to refer him on to someone else – something I try to do, especially if I can’t use someone’s service myself.

It’s something my mother used to say to me when I was a child: “It’s not what you said, it’s how you said it.”

We all need to learn from this – the tone of your communication is every bit as important as the content. Although this is an extreme example, the concept affects every communicator, technical or not.

His parting shot was that he did not want customers like me (paraphrased here) – with a bit of luck, having annoyed me enough for me to put finger to keyboard and write said reviews, he won’t get too many!

23 September 2011

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!

21 August 2011

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?

08 July 2011

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.

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!

30 May 2011

TCUK 2011 getting closer

I learnt a lot from last year’s conference – and got the opportunity to put some of it into practice sooner than I expected. I was very taken with a talk by Martin Block on the use of illustrations and screenshots in user documentation, and any ISTC members (or subscribers) can find an article based on his presentation in Communicator, the ISTC’s publication. I’m already looking forward to learning more on the same subject this year as the specialist stream is Anything but text.

As a self-employed technical author, who has to pay for her own conference attendance and training courses, I often wonder whether I’m really getting value for money – being able to use something I’ve learnt so quickly after the event is a bonus. That aside, I think it is really important to keep up to date with what is going on in my field, as you never know when something you’ve learnt – or someone you’ve met – may enable me to take on a project I otherwise woundn’t even consider. As soon as I have a rough idea what is scheduled for the workshop day on the Tuesday (the programme is a ‘work in progress’), I’ll be signing up. See you there?