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…