How to write instructions

There are lots of books available on technical writing – a quick search of Amazon comes up with over 6,000 titles. No doubt many of them are fantastic books, but it’s kind of tricky to know where to start with a list that long, especially if you have limited funds and can’t just buy everything that looks interesting. A lot of the books are quite large and detailed, which may be helpful for reference or course books, but not when you’re looking to learn but don’t have much time.

Just like Ronseal, this book does exactly what it says on the tin.

The Kindle ebook How to write instructions from technical writing consultancy Cherryleaf is different. It deliberately sets out to be small and light; as a consequence it’s also cheap. It won’t tell you all there is to know about technical writing, nor will it make you an expert overnight. Instead it focuses on one core task and helps you do a reasonable job of it.

The book takes you through the whole process of writing instructions, from researching the topic and audience all the way to publishing. Each step has a dedicated chapter explaining what, why and how. The writing throughout is clear and accessible, making it much easier to read than most text books. It also backs up the guidelines it suggests by explaining why they matter. For example, instead of just telling you to use headings it explains that they’re important as signposts for the reader.

The book goes beyond a set of rules to be followed: it offers choices. There often is no “one size fits all” approach and this book embraces that, encouraging you to decide for yourself which way is best for what you are trying to tell your audience. It gives a number of different possible approaches to ordering topics, organising the information within them and so on. It hits a nice balance, giving you enough information without overwhelming you with too many options or lengthy discussions on their relative merits.

As well as giving stated examples throughout the book the text frequently stands as its own example. In the section on writing topics it states “it’s ok to use an informal tone.” The whole book, from overall structure to the placement of commas, stands as an example of its core principles. The ease with which the instructions can be found, understood and followed is a persuasive argument for following the advice they offer.

I recommend this book to anyone who has found themselves writing instructions but isn’t specifically trained or experienced in it. Anyone with a basic grasp of English can pick up the helpful ideas and tips in How to write instructions and apply them. For my own part I’ve learned a fair amount about the subject in a piecemeal fashion and this book has been very helpful in bringing it all together and filling in a few gaps.

Workification of games

Gamification is all about taking something that feels like work and making it fun. Done right it can encourage return visits to websites, aid learning and get people involved in whatever activity you’re trying to make work. But what about doing the reverse? What about taking a game and making it seem like work? Nobody would ever “workify” something fun, would they? And yet…

Lately I tried a computer game called Lugaru. It’s an open-source, 3D action game starring “an anthropomorphic rebel bunny rabbit with impressive combat skills.” Sounds fun! And it might be, but I didn’t get past the tutorial level. Before you get into the game it tries to teach you several different modes of movement and half a dozen attacks. For each one you are given the instructions on key presses required and then given time to practice in a small, safe area with nothing to look at and nothing to interact with. There were lots of things to remember that all required concentration and co-ordination and the only reward for mastering one move was to be taught the next. It felt like work and it’s not the first time I’ve seen computer game tutorial levels fall foul of the same problem.

Workification happens in board games, too. I’m a bit of a board games fan and own a number by Steve Jackson, including Burn in Hell. The idea is that you trade cards representing souls and try to collect sets of souls that share the same sin. As is common with Steve Jackson games it is littered with amusing caricatures and titbits of information. The problem comes when you reach the end of the game and have to count up points. Instead of just counting cards you have to figure out whether you can double or treble the points for each set, and the whole thing turns into a maths test instead of a game.

A little outside my own experience, a classic example from the world of wargames is Challenger 2000. For an afternoon of moving miniature tanks around a table the publishers provide 90 pages of rules and two double-sided “quick reference” sheets. There is a school of thought that more detailed rules provide a more accurate representation of the real world, though I am assured there are plenty of examples where this isn’t true and more complicated rule sets are just more complicated. From what I understand they tend not to get played very often.

It strikes me that the workification of games happens rather more frequently than would be expected. Does anyone have any examples they’d like to add?

Why I hate learning

I like learning. I like finding out what, how and why. With an engaging and enthusiastic teacher I can become engrossed in almost any topic by my desire to know – even football!* And yet I find learning can be a cause of great irritation.

Push or pull?

Some years ago I read The Design of Everyday Things by Don Norman. It’s a short, readable insight into some of the basic principles of design, with an emphasis on how we as human beings interact with inanimate objects. One section described how a well-designed door handle can allow a person to pass through without consciously thinking about whether to push or pull. Conversely a badly designed one can make you walk face-first into a “pull” door – frustrating and potentially painful. I am in no way a design expert, but I did learn a lot in reading that book. Now when I am faced with a door that I don’t immediately know whether to push or pull not only do I have the frustration of dealing with an awkward door but I also have the irritation caused by knowing it could have been designed much better.

Push-power assisted door

Continuing the door theme, this sign is on a door near where I work:

The first time I tried to go through this door I was utterly confused as to how I was supposed to open it. It turns out it works like an entirely ordinary door, but only needs a light shove to move it. Kind of like power steering, I suppose.

Previously I would have read the sign and been mildly amused at the notion of a door being “push-assisted” given how many doors fall into that category without any need for a sign. But now I’m irritated by how badly laid out the words on the sign are. I can thank Robin Williams for that, having read The Non-Designer’s Design Book. Again, I’m no document design expert but I now understand some of the basic principles well enough to know why the sign is not well designed – the spacing is all wrong, the line-breaks make it confusing and, for my money, the word choice and order could be better. And so my amusement turns to irritation.

Pulling my socks up

The very worst irritation of learning is finding something I did myself and realising how badly I did it. Last week I picked up a document I wrote a year ago with a view to updating it. It’s clumsy and confusing and I was very glad that very few people read it.

Being able to see where I’ve done badly in the past is a step towards doing better in the future, so in that sense it’s good. It doesn’t mean I have to like it, though.

* I used to understand the off-side rule. Really.

The power of tea

My boss made me a cup of tea this morning.

Such a simple, small thing, but I was struck by its power. Usually it’s me that makes the tea – largely from selfish reasons because I like the excuse to walk away from the computer every now and then, and I’m not about to turn down the brownie points.

It may be true that my boss only makes me a cup of tea when he wants me to do something, but as it’s my job to do the work he gives me I don’t need to be bribed. I see it as a gesture of appreciation, respect and equality that someone above me in the company heirarchy will take the time and effort to do something for me that’s totally unnecessary. It’s quite a change from the boss I had some years ago who only spoke to me to pick fault.

So here I am repaying him by blogging on company time. Or possibly by having already finished the work he gave me along side the cuppa.

Tactics for Workplace Survival

Over the years I’ve worked in some pretty poor workplaces. Gladly where I am now is significantly better. This post isn’t about how awful things have been, it’s about how I’ve survived it and how I’ve set about improving things.

Throughout all of my working life I’ve seen things I wanted to improve. Somehow I can’t just sit back and ride the status quo. Along the way I’ve learned (often by bitter experience) some very helpful tactics to survive the working environment and even, on occasion, improve things a bit. Inspired by Tom Johnson’s post on his ‘I’d Rather Be Writing’ blog I thought I’d share a few with you. I dare say you’ve met most of them before, and will no doubt have plenty more of your own.

Learn the rule of 80/20
For any given project or idea, 80% of the benefit can be achieved for 20% of the effort. That last 20% of benefit is much more difficult, time consuming and frustrating to try to achieve. Have a good idea where perfection is, and head towards it, but don’t get bogged down trying to iron out the tiniest little crease when the same time could be used to much better benefit elsewhere. Sometimes I can be a perfectionist and it takes significant force of will to step away from something. Learning when to do that can be a very valuable skill – if you don’t, you run the risk of never finishing anything.

Find what falls between the chairs
There are many tasks that are not anybody’s specific responsibility. These fall between the chairs, get forgotten about and cause a surprising amount of disruption when suddenly whatever they were supposed to deliver doesn’t exist. Sometimes picking up these tasks and making people aware of them can prevent all kinds of pain. Of course, you need to be prepared to have them dumped on your desk.

Bide your time
Sometimes everybody is just too busy to think about better ways of doing things. Bide your time, wait for the lull. Alternatively, wait for a related project to tack your issue onto. That misplaced apostrophe may well be causing you all kinds of discomfort, but re-opening finished content can be a whole heap of awkward (which may itself be something worth tackling). Sometimes it’s better to bite your tongue until it’s being reviewed anyway.

Gather allies
You sole voice singing out against the chorus of apathy is unlikely to get heard. But if you make the right contacts, say the right things in the right ears, you may be able to gather a whole host of people singing your tune. I once asked for an overhaul of some documentation for which nobody wanted to be responsible. I got totally ignored until I made a comment to the training team and they started asking for the same overhaul.

Use jargon – sparingly
Too much jargon and nobody will know what you’re on about. Conversely, if you don’t use any people can assume your job is easy and they know as much about it as you do. Not so long ago my manager said he wanted to review how a particular type of project was documented. Almost without thinking I suggested we needed a content strategy, which got him asking questions and interested. If I’d agreed using his own words the conversation would have gone no further, and there’s a chance the review would never have started.

Keep pushing – but only the big things
Some things are worth pushing for, even when the first answer is a flat no. That only works if you know when not to push things. If you constantly bang on about all your pet peeves people will stop listening to anything you say.

Keep a mental list of tools and solutions
If you’ve got a suggestion of what might help in any given situation people will listen. For example a colleague had been asked to provide a presentation but wanted to do something a bit different, a bit special. The fact that I could point him at Prezi means that he knows I’m worth asking for suggestions in future.

Get acquainted with open source
Going through procurement processes, dealing with purchase orders and getting sign off for spending money is no fun for anyone. You may not even get the tool you want. A surprising number of open source tools is available for all sorts of tasks. They are often free of cost, which bypasses any need for persuading the purse strings to open, and they have permissive licenses that avoid any software control headaches. Notepad++ and PDF Creator have made my job much easier. They took mere moments to download and install, where they could have taken days (weeks?) and headaches had there been a license to pay for.

Get a good manager
Someone above you in the organisation who actually listens to you and has the will to improve the workplace is invaluable. I wish I had some magic recipe for making sure your boss is like that. Unfortunately, the best I can suggest is to keep looking, and in the mean time encourage the boss you do have to do better by showing them the benefits you can provide.

Always be willing to learn and adapt
Every new pitfall you meet is one you can avoid in future. Every accident that works out well is one to be repeated. Every pearl of wisdom is worth filing away for future reference.

And on that note, what’s your best survival tip for the corporate jungle?

#NWTCG

Last night I did something I’d never done before.

It was an oddly familiar feeling to be rushing (crawling, stopping, cursing) through a city I didn’t really know to meet up with people I didn’t really know. Finding myself faced with a locked door in a graffiti-adorned ex-shop front did nothing to dispel either the strangeness or the déjà vu, and nor did finding it inhabited by misfits wearing hats indoors. I couldn’t quite put my finger on it until half way up the unfinished wooden stairs I spotted something I could place: O’Reilly books. Suddenly I knew what was going on. I was on my way to a LUG meet.

I’ve been to any number of Linux User Group meetings over the years, ranging from formal presentations by guest speakers, to bunches of strangers meeting for a pint, to three mates getting together for a cuppa in someone’s house. They all have the same feeling of disparate souls brought together by a deep need to share their chosen subject. The conversations meander around concepts, tools, ideas and anecdotes. There is shared humour that most people just wouldn’t get. There is passion for the ideals mixed with jaded scepticism. There is a desire to offer and receive knowledge and insight.

But last night’s specialist subject was not Linux.

The North West Technical Communicators Group meeting started with introductions that led to tangents that led to conversations. By the time I’d introduced myself I’d already started to absorb the enormous amount of knowledge that was gathered together. It was very obvious that everyone in the room knew significantly more than I did. It was also very obvious that nobody cared, because we had all come with the one and only real requirement: interest.

Everyone, from Robert-from-the-internet (not like that), to John the Content Strategist, to Richard the closet audio wiz, had something to contribute and everyone was willing to listen. The topics covered were as varied as video capture software, content strategy in two minutes and woodland signs. We wandered through statistics, the usefulness (or otherwise) of various social networks, and cultural quirks.

I would be hard pressed to say what I learned, and yet I’m sure I came away knowing more than I had. Maybe it isn’t always the facts and figures that are important to take away from meetings like that. Perhaps sometimes it’s the insight and understanding that comes from being part of the fluid conversation that happens among those with a shared interest.

Stating the obvious

Sometimes life throws random things at you from different angles that happen to land neatly together. Yesterday was one of those times.

I was reading Gordon McLean’s blog post ‘How do you learn?’, which led me to thinking about the Curse of Knowledge he mentions. While something may be obvious to you, it may not be to others.

I was also talking to a friend about the difficulties of blogging. In particular we discussed how you can get half way through writing something and then realise it doesn’t add anything new to the conversation – but you might put it in a way that resonates differently or gets people looking at it from a new perspective, and that’s still valuable.

I’d been doing some googling and as often seems the case I couldn’t find a simple, straightforward overview of the topic I was searching for. Between websites selling related tools or training, and blogs discussing the finer points of obscure aspects of the topic it was hard work to find anything that gave me the basic description I wanted. It was like nobody had bothered to state the obvious.

I think I’ve probably made my point by now, but in case there’s any doubt it’s this: sometimes stating the obvious is a good thing.

Full Circle

Cognitive psychologist Chris Atherton posed the question “What common cultural shorthand does this diagram—explaining Huntington’s disease transmission—ignore?”

This led to some discussion on poor diagram design and Robert Hempsall’s recent blog post explaining why he thinks the entire diagram should be replaced with a simple sentence. This is not exactly a disagreement, just a different perspective.

With a degree in ecology and a Dad into genealogy it’s fair to say that I’ve met this kind of diagram a few times over the years. I still found this particular example difficult to read. There are, to my mind, several flaws that get in the way of this diagram getting its point across.

The first flaw I spotted instantly – red and blue are used to denote a dichotomy among people other than gender (this being the cultural convention Atherton was getting at). This makes it confusing to look at and wouldn’t have happened with any other colour choice, although it’s fair to say other issues could have arisen related to colour blindness and so on.

The diagram uses a different factor – shape – to denote gender. Looking into it further sex seems to be irrelevant to the inheritance of Huntington’s, so I’m not sure they need to show it at all. Not doing so would cut the number of different symbols needed from four to two. Shape could be used to denote whether someone is affected, which would remove the issues I’ve just mentioned.

The next flaw is that the differentiating factor of shape is too subtle. If shapes are going to have meanings they should be obviously different, such as a soft, round shape like a circle contrasted against something spiky like a star. If the shapes can have inherent meaning, so much the better. In this case I’d be tempted to use an empty circle for each person with a big obvious H in those that represent affected people.

The final and possibly most important flaw is that there is simply too much of it. We don’t need to see three full generations of quite a large family when a much smaller family would be enough. Not only would that vastly simplify the whole diagram, it would also highlight the 50% inheritance chance that is currently obscured.

Fixing those three flaws and implementing my suggestions gives something that I think is a lot clearer:

At a glance this tells me almost everything that the original did – barring a few subtleties relating to all carriers being affected. Hempsall suggests the diagram should be completely replaced with words, but I’m less certain. With a diagram there is no reliance on percentages and ifs, which some people seem to be uncomfortable with. Also in this particular case it fits with the standard convention of how inheritance patterns are depicted, which more or less brings us full circle to where the conversation started.

I have always been here (I just didn’t know it)

A few months ago I had a conversation with my friend John:

Me: So, at work I’ve been writing user guides and release notes and stuff.

Him: You’re a technical author.

Me: Am I?

Him: I’m afraid so.

I don’t think I had ever heard the phrase before and wasn’t at all convinced by his assertion but I was intrigued and bugged him to tell me more. It turns out we were both right. What I do doesn’t quite fit the title “technical author” because I spend most of my time doing activities other than writing with information products other than documentation. It does, however, fit the wider term “technical communicator”.

Now, that’s all very well, but my research (and listening to John enthuse about ISTC‘s recent Technical Communications UK conference) showed that techcomms was a very broad and varied field and I like taxonomy too much to leave it at something so generic. The latest big thing in techcomm circles seems to be Content Strategy – another phrase I’d never heard before. Learning a little about that told me that in my day to day job I use a lot of the same skills but have neither the experience, the training or the authority to be a Content Strategist – though who knows where the future lies. Instead I get more involved in the guts of the work – analysing the finer structures, pinning down the details and fleshing out the content. I figure that makes me a Content Tactician.

I did a bit more research (well, I googled), but it doesn’t look like anyone has used the phrase before. One of the things I would like to do with this blog is figure out what being a Content Tactician really means and where it fits into the world of Content Strategy – perhaps even come to some kind of definition. I also want to find out what else I don’t know, and what else I already do without even realising it. The third, and perhaps most important, thing I want to do this blog is reach out to others in techcomms circles because sooner or later John is going to run out of patience with my constant badgering.

I shall need help from people with experience, training or just opinions. Any comments, suggestions or feedback would be very much appreciated – even if you just want to tell me I’m wrong I shall be very happy to have something to think about.