31 December 2012

Opinion, fact and fiction

My career as an author is quite wide ranging. I get to write opinion, fact and fiction in different situations.

Writing opinion is something that happens through this blog, I also had an article published in the recent Communicator. This takes my traditionally-published life to three pieces. I’ve written for a local newspaper (although they have heavily edited and not attributed authorship in the online rendition), conference proceedings on the subject of textbooks (the proceedings themselves will be published in the new year) and now an article for the professional journal. I identify strongly with this genre of writing, and find myself leaning towards it in my other written work (hence the vocabulary and reference choices in my personal blog).

Article, blog and journal writing is actually quite an unusual way for me to write. As a technical author I tend to document procedures grounded in fact. This means that I tend to write with the voice of the company, or the machine. I often imagine that software would explain itself in the voice Commander Data would use if he were coaching an inexperienced pilot over the phone. The linguistic precision necessary in technical authoring and factual writing is in many ways more demanding than that required by any other type of writing (Issac Asimov’s short story Risk sums up why).

Finally, there’s fiction writing. I’ve taken the instincts for detail and control of my writer’s voice from technical authoring and am well on my way to my first novel which should be with us late in 2013. It features confidence trickery and well researched real world locations that will hopefully have some people scratching their heads.

I’d very much like to hear from anyone of my readers who write via the comments section.


19 December 2012

Hear no evil, see no evil...?

I’ve been watching my language lately. No, I don’t mean that I’m worried about the odd 4-letter word slipping out... I mean that I’ve been considering my use of language in relation to my ‘input preferences’. Depending on your background, you may have come across some of these before – whether you are a ‘visual’, ‘auditory’ or ‘kinaesthetic’ person. And so the rest of your 5 senses don’t feel left out, whether you are a ‘gustatory’ (taste) or ‘olfactory’ (smell) person! It follows from my recent training – see Wearing a Different Hat...

The theory is that we all have a preference, sometimes quite a strong one. According to the various tests you can take, my preference is fairly balanced, with ‘visual’ taking a (very slight) lead – but in terms of ‘how I learn’ I’ve known that for a long time.

I used to think I learnt from listening. Why did I think that? Well, I always wanted to sit at the front in class – I thought so I could listen more carefully to the teacher. What changed my mind? I learnt a little BSL (British Sign Language) – and of course, very little was audible. It slowly dawned on me that what I was doing was not listening to the teacher, it was watching. Auditory (listening and speaking) is probably my least favourite: my attention wanders if I can’t see the person talking to me... I start to look at the floor, my neighbour, read the emergency telephone number on the poster by the door, fiddle with something on my desk. You get the picture – and I really have to make an effort to concentrate on a phone call, or I find someone is asking me a question and I’ve been reading at a leaflet on my desk!

Apparently, you tend to use language associated with your preference, so theoretically I would say, “I see what you mean”, whereas someone with an auditory preference would say, “I hear what you’re saying” and a person with a kinaesthetic preference would say, “I’ve got a feel for that”. I’m a little sceptical myself – and feel my language varies more depending on what I’m talking about.

I was trying very hard to listen to myself during a recent training course I was delivering – and also trying very hard not to let the fact that I was listening change what I was saying! So, what did I find?

Well, when discussing punctuation (for example), I said that you can “hear the difference”, even though we were looking at words on a flipchart (so definitely auditory). A bit later on I said I would “guide them through the minefield” (kinaesthetic), and at the end of the day I suggested they “take a look at all of them and see which best fits” (visual).

I really need to record myself as I am sure I missed a lot of instances (I was aware of far more than the three examples above), and although I am fairly confident that my language varies, I didn’t identify a strong preference for one form over the other.


30 November 2012

Wearing a different hat...

I wear a lot of metaphorical hats – more of hats in a minute – but two of my most frequent are ‘technical author’ and ‘trainer’. I am fascinated by the parallels (and overlaps) between the two disciplines – and (depending on your definition of ‘technical’), you could say both fall into the over-arching field of technical communication.

So what are these overlaps? Well, you could look at the ‘collateral’ associated with training – the ‘stuff’ that we produce to help deliver training. There are hand-outs, workbooks, exercises, the ubiquitous presentation, videos and simulations. The decision on who does what really depends on how your organisation interprets the plethora of job titles that attempt to both describe and pigeon-hole what we do: trainer, facilitator, course designer, developer of course materials, e-learning developer, technical author, technical communicator… the list seems endless. The biggest overlap, though, is just that both are about communicating.

I’ve been a trainer/tutor/teacher for longer than I’ve considered myself to be a technical author, and as Andrew pointed out in ‘By popular demand’ (did I see a spot of ‘perk-envy’ there?) I’ve recently been on a 3-day residential course helping me to do a better job of it. I’ve always hated the type of training where you sit in a room and listen to someone drone on reading out one slide after another – I’ve always felt they could email me the slides and I’d do it myself – and this course was certainly nothing like that! (I also get annoyed when trainers proudly proclaim ‘no PowerPoint’, as if reading from a worksheet or a flipchart was any better…) And I’ve refused to deliver training like that – it’s just ‘wrong’.

For the most part, we focused on face-to-face, interactive training – but all the while, I was thinking how what I was learning about How To Be A Brain Friendly Trainer could also apply both to the sharing of knowledge as a technical author and as a teacher in an online environment. During this course, we were both students and trainers – and put our ‘trainer hats’ on (mine was a rather fetching lime-green baseball cap) to indicate we had switched into ‘trainer mode’ – and I learnt a lot from just watching and listening to the others.

My challenge now is to integrate the lively, colourful, interactive and sometimes noisy methods into more of my work, not just face-to-face training – not forgetting to squeeze in a bit of time for quiet reflection when appropriate.


29 November 2012

Ouija Rooms

When I teach and lecture I have quite strong feelings about the rooms I’m working in, so much so that I have an ELT conference workshop ready to go on classroom layout. Some rooms, often with unconventional walls and slightly stretched overall geometry, lend themselves well to workshops where groups huddle round tables, posters and projects, whilst others are more geared towards a lecture format where the lecturer is situated with a panoramic view of the class at the front of the room. In the former I tend to perch on a desk and wander the room offering guidance and answering enquiries, whereas in the latter I tend to want to dance and prowl across the stage.

So what happens to the experienced trainer and communicator when we take away the physicality of the room? The answer, it seems, is that I have a lot of guessing to do. I’ve been in the habit of taking my cues from the room for so long that the virtual conferences I've been having with clients are quite disorientating. For about an hour a week, I’m getting dressed up as a helicopter pilot from the 1980s (headset with boom mike) and joining people in an online “room”. The host of the meeting takes control of one of my monitors (I’m glad I’ve got two, as I can keep my notes visible on the other one) and a disembodied cursor navigates a projection of his screen whilst a variety of ethereal voices speak over the headset. I tend to forget the other people are there if I’m not careful – Alison had to tap me this morning so that I stopped working on the sample files and watching the pointer and started making the little social noises we make when we are in the same room as others, as my silence was not helpful.

I originally thought that using the webcam would help, but the last two experiences have either seen me fielding questions about tropical fish (visible over my shoulder when sat back from the computer) or sitting so close that my on-screen head goes through a hall-of-mirrors-eqsue distortion... and it’s not seeing people I need, it’s having a concept of the room. Unfortunately the closest analogy I can find is Frodo peering into the Mirror of Galadriel, if the mirror was running on Windows 7 with a Ouija Board interface and sporting the disclaimer Many things I can command the screen to reveal - things that were, and things that are, and things that yet may be. But that which is seen, even the Wise cannot always tell. Do you wish to look?. As a result of this confusion my notes now include things like "it’s not a game, remember to respond when people speak" and "don’t sing to aid thinking".


21 November 2012

By popular demand...

The last two weeks have seen a bit of a gap in the blog, something that at least one reader has commented on. It is nice to be wanted, and I guess the problem is that we’re very popular at the moment.

We’ve been very busy here at Clearly Stated... this is not a complaint and much fun is being had by all (perhaps slightly more so by Alison who’s away on a three-day training course in a 4* hotel, but I digress).

In the last two weeks I have done a bit of everything apart from the blog. I wrote a training course for postgraduate students at the University of Nottingham entitled “Writing to Recruiters” and delivered repeat sessions to packed workshops, I’ll return to the fun I had training the educated in another blog post, but this course spurred a mini-push on marketing as I believe the course could be a service offered to firms in the process of making people redundant as part of their resettlement and redundancy package.

I have also been spending time onsite with 4energy to fine tune and update previous versions of their software documentation with new images and some of the exciting new content and features they’ve developed in their continuing quest to cut the cost of cooling.

Finally, I’ve been dusting off my molecular science degree and throwing myself into the world of Li-ion battery technology once again; CD-adapco have a Battery Design Studio that we’re documenting – my time spent in battery labs tells me that this is software that will save research labs around the world a great deal of time and money as the software can simulate tests that would take weeks in real life in moments.

In terms of work-life balance, I’ve also been:

Moving into the new house
This involves moving lots of boxes and spending far too much on furniture.
Discovering that things need doing in the new house
Rewiring, pointing, cleaning... I woke up at three in the morning two nights ago thinking it would be less effort to knock it over and start again.
Raising a baby
Having just decided that Tuesday is “Multilingualism French” day, I’ve got my work cut out for me – He also seems to protest the lack of furniture far more than the big people in the house.

An icon of the modern world once said that the first rule of mass media is to give the people what they want. I will endeavor to make sure the blog keeps happening.


30 October 2012

In sickness and in health

In my teens I took part in the Duke of Edinburgh’s Award Scheme (if you’re reading this and are either under 25, or have kids who are, it’s brilliant and I highly recommend it!). Part of the challenge was the expedition phase, which for me consisted of three days moving through the Peak District on foot carrying full kit. About 20 minutes into the trip (having agreed to carry extra kit for others who were struggling) my knee made a funny noise. I went on to finish the expedition unaided, and then got to spend the next two weeks on crutches.

What, you might well ask, does this have to do with technical authoring? Well, it matters quite a lot because if I’m the kind of person who keeps trekking when every step hurts and I heard – and felt – the snap-crackle-pop coming from my knee (that’s right folks, my body does breakfast cereal sound effects), then in other less painful circumstances I may not notice something’s wrong till it’s too late.

As technical communicators, we sit at a desk for a large portion of our working life. How bad can it be? My knees are not as important for work, but other joints can be essential; elbows, wrists, and fingers do the work, and it’d be a mistake to think that spending your entire life on a too-tall desk with a plank-like keyboard isn’t going to slow you down. You need to go ergonomic (it’s also why professional athletes don’t run in clogs - their feet are what do the business and they know it). That being said, I feel that an overly ergonomic solution wouldn’t work for me, as I often have to work on a computer that isn’t my own and wouldn’t like to lose the muscle memory for touch typing.

The other “joints” are the ones in your spine, and you need to find a chair that works for you. I can think of only one scenario in which an employer choosing a chair for an employee is the best solution, and even then I’d probably want to bring my own cushion. Let’s be clear: your chair, keyboard and desk layout should, as much as possible, be chosen by you. They’re your “running shoes”, and “suit of armour”, and they need to fit your body. It’s why I’ve got different (and cheaper) equipment to that in Alison’s work-space, because it fits me and means I can work better for longer in more comfort.

I realise that in working with family, I have certain advantages, in that Alison actually cares about my health, rather than just the work I bring in, but if you need to parley with your employer, try using phrases like “increased productivity”, “less time off sick” and the best of the bunch “cheaper to buy a £50 keyboard now, than pay my carpel tunnel syndrome lawsuit a decade from now”! Your boss, together with your spine, will magically become flexible again.


18 October 2012

Documentation for Prometheus

I was lighting the fire at home (a complex affair involving kindling and logs that I’d split myself, and a general feeling of manly can-do-ness). I turned to the homunculus and pointed out that before very long he’d be building the fire and chopping the wood, at which point his mother raised an eyebrow at me in quaint disapproval.

The lighting of fires played an important part role in my early years. I was in Cubs and then Scouts and loved going on camps. For me as a child, lighting a fire meant I was on an adventure, about to enjoy a barbecue, or both! Perhaps my favourite euphemism for a fire is “caveman TV” as even when nothing’s cooking, the way flames move is fascinating.

Fire also served as my introduction to technical writing as the first document I ever produced was a poster on fire lighting for display at a camp-craft competition and to gain my photography badge.

Of course it was a far cry from the modern documents I produce. It was 20 years ago and the world was still very analogue. It consisted of a sheet of cardboard that had been curved slightly so it would stand, twelve photos taken on a 35mm camera, and handwritten instructions regarding the gathering of fuel, the building of the fire, and the best technique for lighting. Once the photos and the instructions were on the sheet of cardboard, it was covered in cling-film to waterproof it.

I did get my photography badge, but I also learnt a lot about matching production to client needs. I’m very unlikely to produce handwritten documents that are attached to a discarded piece of cardboard now, unless of course the end user is going to be an 8 year old child who may need to roll that document up and stick it in a backpack, and then later tear an edge off the document to use as an improvised fire lighter. I spend a lot of time very impressed with the technology I get to use as part of my job, but it’s important to always match that technology to the needs of the end user, not the whims and abilities of the author.


08 October 2012

Slow-roast documentation

Yesterday was my wife’s birthday. As a result I spent 3 hours in the kitchen, accompanied by “technical documentation”. I cooked a “special meal” and that meant resorting to the most ubiquitous of tech-doc... the recipe. I don’t often use recipes, most of the time I prefer to either make it up as I go along or, better yet, let someone else do the cooking! However, when it’s an important meal, I write lists and use a recipe for everything that goes on the plate just to give me peace of mind.

I could tell you what I cooked, but I feel that if I dwell too long on the succulent stuffed leg of lamb and its various accompaniments the generated drool would swamp your keyboards. Instead we’re going to explore where the recipe came from, and how it impacted my view of “documentation on the web”.

I got the recipe from TESCO (for foreign readers, TESCO is a large supermarket chain; don’t worry, they may be extending a corporate tendril opening a store in your country soon). I didn’t buy the recipe, I obtained it from the Real Food website they manage. The website is essentially a massive cookbook with multiple search options. The website has become a favourite of mine because I can search for recipes based on what I’ve got in the fridge, the time I have to cook and how many people I’m looking to feed – apparently it’s also possible to search by calorific content, but that would just take the fun out of things. The first observation about the production of documentation is that people are more likely to use it if they can find what they’re looking for. This may mean that we want to reconsider packaging documents into .pdf format quite so often, especially when we’re dealing with end users who aren’t so comfortable with pressing CTRL+F. On-line shopping portals offer some excellent guidance as to how information can be sorted and filtered by the end user and it would be nice to see such an approach used more widely in technical documentation.

It didn’t all go smoothly with the meal. The juicy agneau rôti was on the big side, and as a result the timings in the initial recipe didn’t really work. This meant that the family got to wait an extra 45 minutes for their dinner. I posted a comment on the recipe page, and was pleasantly surprised when the team responded by updating their recipe as a result of my comments. I feel that this shortening of the loop between the author and the end user is a good thing, especially when it results in tangible benefits and essentially “free” usability testing... now all I’ve got to do is convince them to send me free food and all will be well!


05 October 2012

A meeting of minds

This week saw Clearly Stated attend TCUK in Newcastle. Alison was presenting whilst I was there to soak in my first conference in the profession. I've been looking forward to it for a while (see “Here come old flat top”) and was not disappointed. It was a good conference, so good in fact that it is quite a challenge to write a good review without using the slang of my youth – it was ‘wicked’.

Highlights of the conference for me included meeting David Farbey, who is one of the tutors on the Sheffield Hallam MATC and – as I discovered this last week – an ace conference chair with a good sense of humour. The trepidation I felt at stepping back into post-graduate study quickly evaporated, and I’m getting really excited at continuing to push myself as a technical author. There were also a variety of thought-provoking presentations including one on the no-man’s land between intuitive devices and technical documentation.

Even more important than the presentations (in my humble opinion) was the presence of so many other technical communicators with differing and complementary backgrounds that spurred discussions about DITA, explanations of XML, and wrangling about Word - not to mention banter about body text. I’ve come away from the conference with the feeling that even though technical communicators may sometimes work in solitude, we are part of a fun supportive community that really cares about the profession.

What this all boils down to is the heart-felt recommendation that if you’re a technical communicator and you’re serious about your profession, you should be booking in to TCUK 2013 as soon as it’s announced (or even better, participating and becoming one of the wonderful speakers the rest of us get to enjoy).


29 September 2012

The ALARP Principle

Have you ever tried typing with waterproof plasters around two digits? That strange splint-like feeling where you’re reduced to using rigid digits to strike keys means things happen more slowly than usual. I know this because as I type this post the thumb and index finger on my right hand are immobilised in this fashion. This was a small wood-cutting accident brought on by my own willingness to be helpful.

It doesn’t hurt... cut deep enough and the sensation just ceases. It’s just numb and immobile. Having an accident brings me neatly onto the course I’ve been on for the past week and one of the lessons I’ve learnt that will inform my practice as a technical author.

We learnt about the ‘ALARP principle’. ALARP relates to the management of risk and stands for As Low As Reasonably Practicable. This principle is grounded in the work of the Health and Safety Executive. (For foreign readers, this is a government organisation which is much maligned for introducing ‘red tape’. In reality they’re very good at making sure food is safe to eat, and that workplaces have First Aiders. They’re probably the main reason that our newspapers aren’t filled with stories of people being cooked alive in their workplace because the management have decided to use the fire exits for additional storage space...)

The documentation I’ve been working with this week is all to do with the processing of explosive munitions and it makes for very interesting reading.

The weight of legislation in this sector is immense, and the requirement for good documentation cannot be understated... and what is considered ‘reasonably practicable’ is still more dangerous than many other activities. For this reason facilities have hardware and accompanying policies and procedures in place to deal with everything up to and including lightening strikes, and it would appear the level at which they cease documenting and planning is up somewhere between ‘tornado’ and ‘meteorite impact’. This is also reflected in the precision of the documentation. That being said, the subject matter is still high explosives and there are always going to be risks, which is why the focus is on ALARP and not total elimination, which would see this industry unable to function.

When I consider the main business of Clearly Stated, I can see ways that we apply the ALARP principle to our business practices. Clients’ documents are protected against fire, power and system failure, and flood. We use a good quality virus checker for everything. But there are potential events (like alien invasion) that we just can’t plan and prepare for.

I am also going to use ALARP as a principle when authoring, considering the risks encountered by the end-users of my documentation. Is it reasonable to expect the users I’m writing for to ‘experiment and play’ with a system, and can I allow for this in my authoring in order to reduce the risk of them or the system getting stuck? Do users need a lot of hand holding? Well, again that depends on the anticipated user and the system, but I am also conscious that ALARP-friendly documentation may not cover every eventuality (like alien invasion) in favour of practicability.

This brings me back to the damaged hand. Yes, I cut my hand, but the axe was necessary in order to have a nice warm fire going to keep me warm during dinner. An ALARP-friendly axemanship manual wouldn’t say, “Don’t swing the axe”, but it would have a section on the application of plasters and dressings!


12 September 2012

Multiple monitors

Alison’s desk, featuring two portrait monitors and a smaller offset display.

Part of the fun of working for Clearly Stated is being able to specify (within limits) the hardware that I use to do my job. I’ve got two widescreen Iiyama monitors (the reason for this particular link is that we’ve been buying from Continental Monitors for some time now, and their customer service and pricing is brilliant) that I have set up in landscape view at eye level, forming a wall of images, documents and data when I’m working. Alison uses three monitors, two of the same Iiyama model in portrait mode together with a regular Philips monitor offset to the left for dealing with graphics, timetables and emails. The speed and efficiency this lends to a technical author dealing with multiple images and documents at the same time is fantastic, as it saves having to constantly flit backwards and forwards between different windows, or finding that the drawing toolbar in Framemaker has decided to hover directly over the document being crafted. With multiple monitors a technical author can fly.

My desk featuring two landscape monitors.

It hasn’t always been like this though. In my last post with the Royal Air Force of Oman, I was responsible for authoring a language textbook. This was a full colour, illustrated affair, and my employer had very nicely paid for a top of the range Mac, together with InDesign and Photoshop CS5, and as the geek on the team (there were other authors, but no-one else willing to play with the new software) it was my job to turn stuff into a presentable textbook. For about two weeks we cantered along at a reasonable pace, and then it happened. I was picking up toner cartridges from the facilities office when I saw – gathering dust – a 15” TFT monitor. I expected to have to plead, and maybe even grovel a little bit, but I was assured that “this computer doesn’t work anymore” and was allowed to take it by quizzical but helpful staff.

Two monitors! I was rich! I was flying! There was a display for graphics, images and source documents and another for the finished item... but my boss didn’t like it. It meant that I had a wall up, and from his perch on the far side of the room, I was concealed by a parapet of screens. My work-rate went up and the distrust diminished, but I do think the guy had a point. From the back multiple monitors do form a barrier, and it’s important to create an office environment where nothing is “hidden”.


03 September 2012

Meet the audience

Many years ago, I had my own radio show with WONB. It was great fun, and I still have the ability to write copy that takes exactly 30 seconds to read out, amazing memories and a fairly eclectic knowledge of music pre-2003.

Listeners used to phone in and sometimes send letters or cards. One old man sent a nice card after I’d played a song that reminded him of a girlfriend from the 60s, whereas others would request songs or phone in with jokes and comments on the day’s news. The fact is, with any broadcast medium – and I’d include blogs and technical documentation in this category – the audience for our message remains largely unknown. There is therefore an inherent danger in these little glimpses into our audience. In the case of the old man who sent me a card, I had to consciously resist the desire to play all the songs he would like and ignore the silent majority of listeners. Similarly, although one esteemed friend from Pakistan has identified himself as a reader, and Google tells me I have readers from a host of different parts of the world using a variety of browsers (hello to all those reading this from France!), I am resisting the urge to write for him or any of the others I know are reading this blog. Instead I write for the generally educated reader, who has some curiosity about the working life of a technical communicator.

This brings me nicely onto the subject of analysing readers. I’m sure many of us have had the opportunity to meet a selection of end users, particularly when working on internal documentation or planning a training course. Although valuable, I feel this experience should be approached with caution, primarily because I’ve often been the guy who’s been nominated to speak to the “special visitor”. The fact is that unless the client’s business is staffed by Oompa Loompas, or the Borg, the individuals you meet will be probably be outliers. The same happens when shooting TV commercials. A company that uses its own staff rather than actors in commercials may still choose their more attractive staff or those who represent the aspirations of the company rather than the reality.

How can you tell whether the people you meet are outliers? First, look at the room where you're meeting them. Does it resemble a scene from Mary Poppins, or Columbo? If there are cakes, biscuits and drinks available then you may be talking to the cream of the crop who’ve been given a “bit of a treat” by the boss; alternatively if the room is bare apart from a tape recorder and a panic button, you could have been given someone from the bottom of the pile. The other way is politely enquire, “I do hope this isn’t taking you away from anything else important?” If they respond that it’s just a normal working day and they’re pleased for the break, then this is a good sign... if the suspect person helping with enquiries explains that today’s the day the entire office was due to abseil down the side of the building in aid of a children’s charity, then you’re either faced with an above average “job comes first” individual, or the one who’s rarely left alone with his own thoughts and shoelaces, much less climbing equipment. Despite these observations, what you learn from the process will be valuable. These observations serve to temper and qualify the data collected and ensure you are broadcasting a message, not unicasting.


31 August 2012

“Here come old flat top”

Now I know that many readers will be thinking, “This guy’s meant to be an author, yet the grammar in his post title is awful!” But then it’s not my grammar: it’s Lennon and McCartney on the subject of meetings. ‘Come Together’ really is an amazing piece of music, and I have always imagined that it describes a conference for a profession that time forgot... like the annual penguin shepherding convention, which sounds silly but is something I’d like to attend just for the banter value.

This year I’m attending my first TCUK in Newcastle and – having just filled out my workshop preferences form – I’m looking forward to great things. Of course as a theme tune we could never use ‘Come Together’ by the Beatles, as we’d suffer minor apoplexia due to the grammar (and anyway, we’re not that ugly). I was half thinking about the Beegees’ ‘I’ve just got to get a message to you’, but then I realised that, as conference themes go, it’s quite morbid. (It’s sung by an individual on the way to the gallows who’s looking for a chance to apologise rather than being technical communication based.) In fairness, it may be fit for a political party conference, given the current state of affairs.

So what piece of music could work for the TCUK conference? I wracked my brain and have two suggestions. The first is ‘Calling Occupants of Interplanetary Craft’, which I feel is a song that could well have been written by a technical communicator, given the precision of the lyrics and the range of vocabulary used. I’d like to think that if ever we did encounter aliens, there’d be at least one technical communicator on the scene to stop some boffin or politician saying something that’d get us assimilated, exterminated or made the subject of some ritualistic predation.

Option 2 is a cool yet understated instrumental, like the Bond theme played on a harp (I wrote the blog before discovering someone had actually done this!). This would work because, firstly, tech comms is an extremely cool profession, and – like 007 – we tend to find ourselves working in many different sectors. Secondly, whilst 007 may be able to diffuse a wide range of explosive devices and pilot any vehicle known to man, he’ll only be doing so because a technical communicator has done it before him and documented how it’s done.

So, I’ll see some of you at TCUK. Some of you will just be missing out by not going, and some of you will be reassured that Clearly Stated are staying up to date and at the forefront of the profession, no matter what theme tune is playing in the background.


30 August 2012

Business Development

This week I’ve been looking a bit more at the business development function within Clearly Stated. In the current economic climate it’s probably more important than ever that the business continues to grow rather than stagnate or shrink. We now have two full-time authors (Alison and me) and we like to stay busy.

I’ve done business development before, and in that post I've been a “business development manager” with a fairly broad remit which took me to assorted trade fairs, networking events and cold calling (or at least luke-warm calling) various potential clients. In a smaller organisation, business development is often an also-ran alongside other duties. The secret is to take just enough time away from current work to ensure that there will be more work to do a few months down the line. It is a difficult balancing act: spend too much time finding new contracts and the current work suffers, whereas spend too little time and sooner or later the work is going to dry up.

The ISTC works very hard to ensure that the profession is recognised, and most of our clients seem to have a clear idea of what they want from their documentation – even if that subsequently changes and adapts – and actively seek us out. I am aware that there is still a lower recognition threshold in wider society as mentioned in an earlier post. I won't be cold calling in this job. Rather, business development means a few things that it might not in a different industry and is very closely tied to CPD.

We prefer to work on projects that enable us to develop our industry experience, to stay current and continue moving forward. For example, much of the software we currently document is based on a traditional keyboard and mouse operated computer. I’d love to start working with anything that uses the new touch and motion sensing technology that’s out there, as within software documentation, this will involve a volte-face in the way the actions of the user are described. Instead of left and right click, we’re getting “tap”, “drag”, “draw” (and possibly “flick”, “glide” and “massage” depending on future developments in the technology) and a whole wealth of other language that will gradually become standardised to explain how highly tactile, multi-contact point touch screen devices are used. I have some experience in this as I trained colleagues in a college environment on the uses of interactive whiteboards, but if anyone out there is writing an app, or porting their existing system towards the newer interface systems, I’d love to come and compose your documentation for you (which may or may not be “writing”, there are all manner of equally cool options available through Robohelp, Captivate and a wealth of other packages).

The second part of the business development game is the education of the individual communicator, and that doesn’t mean just learning software packages (although that’s essential) or taking an MA (although that starts in the new year). It means reading widely and well so that we are able to parse the world into chunks we can communicate about. Later on I’ll be including a whole range of book reviews in the blog, partly out of interest, and partly to showcase some of the things we’re encountering and learning here at Clearly Stated.


20 August 2012

Version control

One of my favourite cinematographic scenes is in Men in Black, in the room with all the impressive outer-space technology when K turns to J and says “This is gonna replace CDs soon; guess I’ll have to buy the White Album again...” I love this scene because it points to some forms of expression and art being timeless. I guess I am the kind of person who enjoys certain films, songs, games and books in a way that will stand up to time, I actively enjoy watching Zulu, whether it’s on the TV, VHS or DVD, and will probably enjoy watching it in 30 years time on whatever format we use then. The issue then is, with the exception of the transition from DVD to Blu-Ray (as a Blu-Ray player plays DVDs as well), titles are continually re-purchased. Looking at my dad’s music collection, I can see the same tracks on vinyl, CD, MP3, and I know there was a tape in the late ’80s that perished after far too many summer days in the car.

I accept that progress happens, I also accept that an iPod stores far more music by volume than a tape, and that it’s unlikely to melt in the car. I also get that any machine that accepted all possible media formats is more likely to resemble a creation of Dr. Emmett Brown than something you'd like to install in your living room. However, when I look at my professional life, I find this need for multiple versions incredibly frustrating.

On my desktop right now 3 separate versions of Adobe FrameMaker are installed (7.2 running on a virtual XP machine, 9 and 11). I have access to every version of MS Word (and Office) since 1997; I still have the discs and licence for all of these “just in case” a client has a specific requirement. There are serious issues with this need to keep slightly different software iterations around “just in case”. The small box of discs that I started out with in the ’90s is now a “software cupboard” where licensed software is stored just in case it could one day save the world (almost like a software “man drawer” ). This need for a cupboard, and the virtual machine, is partly generated by software companies not building in true backward compatibility – yes, I can open an old file in a new version of the software, but once I save it, it can never be opened again by a client who’s not invested in the same version of the software. The current solution is the cupboard, but I am becoming increasingly enthralled by the various “cloud” approaches out there (Adobe and Microsoft both have offerings in this category).

The theory with the cloud is that I get access to whatever the latest version is (including patches/service/support) for a monthly fee rather than a single, and sometimes intimidating, one off cost. I feel that there are many advantages in this approach, and the version number could almost be set aside to instead be replaced with the knowledge that for a a monthly cost, I am always up to date. I feel that subscribing to a rolling “cloud” based programme would do away with the software cupboard in the long term, although I am deeply concerned that the companies putting these offerings together should be aware that occasionally professional technical communicators may need the ability to roll back their installations to handle “legacy clients”.

I’d quite like comments on this post, especially from anyone involved in or experienced with the type of cloud based systems we’re considering subscribing to.


14 August 2012

Walking the line

Today has been a strange work day. This is in part because I’ve not had a full night’s sleep in nearly a week on account of becoming a dad. I’ve come to realise that meeting your children either early or late can lead to sleepless nights; whilst waiting till destiny forced me into a deadly light-sabre battle might have been waiting too long, being there at the time of delivery is also quite “epic” in the demands that are placed on a father. In a more ideal world, I think I’d like to meet the child over a cup of something warm (tea, or in his case milk) at a time when no-one is screaming or thinking about using anything sharp on anyone else. That’s not the whole story though, in between the frantic mad dashes to hospital, the sleepless nights, the assembly of nursery furniture – on the subject of technical authoring, the instructions for assembly were very good... and they’ve finally fired the guy at the furniture factory who used to put one extra bolt in the packet just to trigger any latent OCD – not to mention deadlines for various clients there’s been today, which is best described as a “lull”.

This doesn’t mean I’m doing nothing. I’ve got Clearly Stated set up with a Facebook presence, and have started teaching myself XML. This means that I’m working on marketing and capacity building. It somehow doesn’t feel enough; maybe that’s because I like measuring my output and it’s far easier to point at a document I’ve written and say, “See, I’ve been working, I wrote that” than it is to say “I learnt stuff” and expect it to be counted. This is a fairly recent development: I’m not sure whether it’s because I’m working in the family business and don’t want to let people down, or because I’m about to be paying a mortgage, but a few years ago the idea of spending an employer’s time reading a book (fiction) and on Facebook (commenting sarcastically on assorted photographs from around the world) seemed like the perfect way to spend my time. Now, even when stuff is most definitely “vocational” and “relevant”, I feel some measure of guilty angst that maybe I’m not getting quite enough done. Hopefully, I don’t become complacent. I feel that part of being professional, and responsible, is having the ability to self-monitor and make sure that the activities we are involved in are in some way relevant to our profession and the job we are asked to do as authors. After all, it is far easier to quickly minimise an inappropriate browser window or leisure-app than it ever was to palm a Steven King novel under a textbook and remain undetected. I think the man in black (the one with the guitar not the light-sabre) would describe this behaviour as “Walking the line”.


05 August 2012

The education of readers and writers

I remember clearly many of my secondary school English lessons. Perhaps one of the most interesting lessons was on the subject of how stories begin. Several options were presented ranging from the somewhat clichéd “It was a dark and stormy night” through to the more nuanced but equally as suggestive “to Sherlock Holmes she is always the woman”. The central thrust of the lesson, after going through various successful opening lines – or at least the opening lines to successful works of fiction – seemed to be that there wasn’t really a right or a wrong way to begin a story, so long as the author managed to in some way reach into the mind of the audience and plant a question or two or three that would make them want to read more. This reader would continue turning the pages like some literate, speed reading dervish until such a time as those questions were answered, the book was complete and the reader left shocked, amused and fulfilled. Being older and cynical, I also imagine that these answers would need to be rooted far enough into the book that they couldn’t be quickly answered by someone having a surreptitious shufty in a book shop, thereby forcing a sale and the generation of royalties.

In school, and maybe this was just the 1990s, there was always this sense that people wrote either stories or essays, with the occasional recourse to poetry (particularly the intricacies of iambic pentameter) and plays (presumably for either those who could only write dialogue, or for those who found quotation marks offensive). This probably explains the conversations I’ve had recently where I’m initially asked what kind of story I’m writing. I tried getting ahead of the curve with one old friend by starting out with “technical author” rather than “writer”, and received the reply “well, you were always interested in science fiction; does it happen in space?”

My inner cynic tells me not to complain too much, as this lack of understanding reflects a fairly broad niche that technical authors are required to fill. When looking at the bigger picture I feel that, just as there has been a recent push to replace the older IT syllabi with something that will better gear the UK for a technological future, there could be a matching push to move the art and craft of understanding, manipulating and using words to better reflect the way modern professional writers often write.


30 July 2012

Colourless green ideas

One of the reasons I enjoy writing and training is because I enjoy words. The way vocabulary can either flutter past or dive-bomb the awareness of an audience is a constant source of both amusement and stimulation. Today we are going to use colour based metaphors to explore the way writing sometimes works. The vocabulary of a writer is the palette from which he creates; just as one would probably not paint an office in byzantine paint, or a disco in battleship grey, the way in which we use vocabulary when writing correlates strongly with the context of the writing.

Many readers at this point, especially my friends who write “creatively” will be thinking that they are doing the byzantine, or even polka-dot neon writing whilst “technical authors” are limited to battleship grey, with possibly a little magnolia thrown in for good measure. I’m afraid to say that you’re only partially right; technical authors are not into psychedelic writing, but nor does monochrome really work. Whilst the creative writer can allow for departures from reality and the occasional moment of deus ex machina, for the technical author, reality is our linchpin and the devil really is in the details. A creative writer may forget to have a character reload once within a half hour long fire-fight especially if the weapon system is sufficiently futuristic, whereas the technical writer will need to explain exactly how reloading happens, or how the fanciful futuristic firearm functions (try saying that fast!) in a way that’s both accessible to end users and the purchasing authority responsible for materiel* supplies.

If we then return to our metaphor of colour we find that technical authoring has “word schemes” the way a wedding will have a “colour scheme”, and that we will write within the confines of those word schemes to exact and powerful effect. At least within the work I’ve been doing recently the majority colour scheme seems to be Dagobah Green with hints of authority. When documenting software there is a real sense of having users “do or do not do.” The idea of trying, or of having users attempt something that I haven’t already fully explored is just not an option in this case.


*Note for the eagle eyed: As a rifle is a military supply, this is not a spelling mistake!

24 July 2012

Writer's voice

Today I had the pleasure of lecturing at the University of Nottingham to a multi-disciplinary group of students on a summer programme from China. It was a 3.5 hour session; those of you who deliver training or teach know that this means I spent most of Sunday preparing. The session was titled “Reflection in Education”, and seemed to be well received. It has given me a few ideas for how Clearly Stated can bolster our selection of courses and training. It has also made me reflect and develop this week’s post. Nothing quite like taking a dose of my own medicine!

What I’ve been reflecting on is “voice”. (I’m not meaning to theme my writing quite like this, but the conscientious reader will notice that last week was all about the art of listening.) I’m not talking about diction, clarity or volume – even though some trainers could do with working on this – but rather the curious ability a great singer, comic, storyteller or trainer has to take an audience on a journey. This strange talent seems only tangentially related to the quantifiable characteristics of speech, and instead is an ever changing blend. In front of an audience, you’ll know when you’ve got it: the room will hush, still, ready to erupt with applause, laughter, tears or even raised hands and appropriately thought out questions. I found this speakers’ Elysium today and it was good. I’ve been doing this verbally for a while now and a love of public speaking is a big part of why I became an educator and trainer to begin with; whether presenting a new product, first aid or something far more esoteric, people tend to listen.

Let us then examine the presence of voice in some technical communications. It seems to exist most often in the genre as the garbled love child of jackanory and a dalek, “Are you sitting comfortably, then I’ll begin; press the red button to EXTERMINATE! TOTAL DOMINATION WILL RESULT!” Finding our voice as writers is probably more difficult than doing so as speakers, especially when the prime goal in our communication is not to entertain. Again it is not so much the mastery of register, grammar or typeface, but some marvellous mixture of all this and more.

I’ve decided, in my continuing quest to seek out new ways of writing, to aim for "nurturing yet firm". Time – and client feedback – will tell.


16 July 2012

A new career

Somewhere out there are people thinking “technical author, what’s that?” If you’re a company thinking you might need a technical author then that question has already been answered from your perspective. But what if you’re a student, or a jobseeker, trying to work out if this is something you could do and something that you would enjoy doing? It’s all very well talking about the services a technical author can provide, but what is it like to provide those services?

Well in this week’s post I intend to answer those questions, by letting you know some of what I’ve been up to this first week on the job. Just bear in mind that I’m writing about software (mainly) for the people trying to use it!

The first thing to point out is that I’ve been writing. Now I know some of you are sitting there thinking “but I write all the time... I’ve got a blog all about my favourite ice-cream flavours and it gets a few hits, mostly from my mum, and hey I did all those essays in university, not to mention the short story I’ve been working on in those rare moments that creativity has struck for the past six months.” Now this might sound rather horrid, but when I say I’ve been writing, I mean I’ve been making words appear on paper in a very structured way during normal office hours. The subject matter is dictated by clients (so unless you’re very lucky, it won’t include your favourite ice-creams, and the motivation has to come from elsewhere). I also haven’t been involved in the near-séance-like process of pulling an academic essay out of nowhere at 3am, whilst slightly intoxicated, in order to pass a particularly odious module. 40% may have been the pass mark on your degree, but it isn’t going to cut it when people are paying for a client-facing document. As for the idealistic glint in your eye that yearns to write only when feeling creative and inspired... well, in some contexts you’d be looked at as if you’re crazy, in less understanding offices you’d probably just be fired. So if you think this is for you, you need creative and communicative flair, coupled with a sense of diligence and purpose that would make a spartan’s eyes water. This will extend not just to the words, but to the software you are using to compose those words, as you are expected to create documents that not only read well, but that are technically well composed.

Second on the list of things that I’ve been doing is “listening”. There are two distinct types of listening involved in technical authoring. The first is listening to some very smart people describe, demonstrate and explain things in a way that makes sense to equally smart people. All this whilst frantically taking notes, trying not to sound too dense and work out how you’re going to get it all into 3 pages, with some illustrative diagrams and words that can be understood by the “generally educated reader”. This is about as difficult as it sounds, and the learning curve will be very steep. If you get hired by an organisation as an “in house” technical author, this may last from between a week and a month. If you’re even thinking of working for an outsource authoring firm, you’ll go through this several times a week, often on completely different topics (last week included cooling systems, educational software and supply chain management). For me this is the best part of the job, but if you are the kind of person who feels overwhelmed by masses of information and details this isn’t for you (the ability to keep organised, decipherable notes is a plus). Most new technical authors will either have to spend time learning to write appropriately for different audiences (if you have a science/technical background) or catching up on the core terminology and principles of various fields (if you’re from a languages/arts background). The other type of listening a technical author does quite often is taking on-board feedback and criticism of their work. The only emotion you can really afford to have invested in the work you do is pride in the finished product, but any sense of ownership that might lead you to crying in the corner when it’s pointed out that you’re missing the point or that your carefully crafted diagrams aren’t really that helpful and need to be redone needs to be checked at the door.

I have completed a document that went off to a client, and came back with only one small amendment. This created a buzz, a sense of pride and a feeling that I want to do the same thing again. Part of being a technical author means being pleased with results that are measured in this way.

I hope this helps. In the words of the big man himself (the Austrian, not the Irish) “I’ll be back”.


11 July 2012

A new addition to the family (business)

I’ve joined the family firm; or rather I’ve transformed the one-woman-show of Clearly Stated into a family business through dint of being available and appropriately qualified during a very busy period.

On my “to do” list for the first few days is a blog post to introduce myself to the wider world. It also says here (in Alison’s handwriting) that I am to avoid any references to The Godfather movies, or the word “debutant” (oops!).

This then is my first blog post. It’s quite exciting to have my writing recognised as being “work”, rather than just being something an employer expected me to do – for them – in my own time. I’ve always been proud of my ability with words, and with documents in general, and have found writing to be an unwritten part of my job description in the past. I have created documents ranging from briefings and proposals for major projects through to incident reports and training materials, and I am looking forward to creating high quality materials. I’ve served an on-off apprenticeship with Alison over the years, and together with my own background in education and training hope that I’ve got a lot to offer.

I’ve already started working on one project – under supervision – and I’m excited as the products we are documenting are already making an impact out in the real world. There is not a huge difference between my professional writing style and Alison’s, and so we will be continuing to produce clear and concise documentation for our existing clients. That being said, I do have some ideas of where I’d like to take my skill-set in future, so watch this space…


15 April 2012

Online post-its

Although I’m not a believer in technology just for the sake of it, I am always on the lookout for anything that will help make my life just that little bit easier.

Anyone who has attended one of my writing skills courses will know that I suggest a number of ways of ‘getting started’, of planning that document to make sure it achieves just what you intended. I’m also a fan of post-it notes... the ability to put something in place but then move it around without any difficulty and ‘fix’ it somewhere new really helps me when grouping and ordering information. I was recently introduced to an online equivalent.

Lino It is very easy to use, and helps me to visualise my document very, very quickly. I’ve only been using it for a relatively short time, but can already see the potential. You can keep your posts private, share them with a select group, or make them publically available. You can rearrange, overlap, edit and remove post-its at will. You can ‘pin’ other items to your board (photos, plans, screenshots) and even – and I think this one has real potential! – upload an image to use as a background. I will play some more and come back to you, but I have a mental vision of a mind-map background overlaid with post-its. Wonderfully creative!