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).