tag:blogger.com,1999:blog-42308068557998605662024-03-13T11:32:46.197+00:00Clearly Stated BlogMusings on any issue related to technical communication, in its broadest sense.Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.comBlogger71125tag:blogger.com,1999:blog-4230806855799860566.post-1012334222156448532015-12-14T16:31:00.000+00:002015-12-14T16:31:48.038+00:00Technical Communication UK 2015<p>As usual, I attended the <a href="http://www.technicalcommunicationuk.com/">Technical Communication UK</a> conference (TCUK 2015), which was held in Glasgow this year. As my father came from Coatbridge (a few miles east of Glasgow), the accent and the general location felt very familiar to me, and after several years of attending TCUK, so did many of my fellow delegates! It’s one of the things I really like about TCUK – the change to catch up with people I don’t see very often and find out what they’ve been doing lately.</p>
<p>I didn’t attend as many sessions as I normally do – but that wasn’t the fault of the organisers. I’d seen some of the presentations before (I attended UA Europe in the summer) and I needed to have a few conversations with people while wearing my president hat. Overall, though, another excellent conference. Some of the take-aways:</p>
<ul>
<li>Diversify – if you can do something your competitors can’t (competitors either in the job market or amongst your colleagues), you have an advantage.</li>
<li>Keep up to date – you may have years of experience, but being a wizard in Word Perfect and in working practices of the 80s isn’t going to get you far.</li>
<li>Embrace your inner nerd – if you’re fortunate enough to have one. We are often told (or at least, I have been) that we shouldn’t be too technical. We write better user documentation if we are closer to them than to the developers. But there’s nothing wrong in being technical if your audience is technical, and in any case, being technical in your own niche (for example, XML, CSS, DITA, HTML...) can be a definite advantage.</li>
<li>Things are changing quickly – but there are always some who for various reasons choose to (or have to) keep doing things in a more traditional way. If there are sound reasons, that’s fine - but don’t just keep doing it the way you’ve always done it just because that’s the way you’ve always done it! Some of the things that are now being done in production environments (virtual reality and so on) are amazing.</li>
</ul>
As president, I also had the privilege this year of presenting the <a href="https://uktcawards.wordpress.com/">Technical Communication UK Awards</a> to some very deserving winners. The challenges overcome to produce some of the winning entries were inspiring.Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-75662209723715255872015-09-08T14:27:00.000+01:002015-09-08T14:31:40.122+01:00Terrorist Tech-Comms<p><i>*This article was written for my regular slot in <a href="http://www.istc.org.uk/publications-and-resources/communicator/">Communicator</a> but didn’t make it to print as it made a copy-editor “uncomfortable” (you have been warned!)</i></p><p>Do you remember <a href="http://www.guerrillagardening.org/">Guerrilla Gardening</a>? The alliterative environmental resistance movement that swept some of our inner cities a few years ago and saw people improving our urban spaces using tactics that would have been quite <i>de rigueur</i> for the French resistance? Well, maybe the same thing would be possible for the world of technical communication? Of course, if we’re going to borrow combative methods and retain the alliteration, terrorism becomes our playbook of choice.</p><p>Modern global terrorism (as opposed to the localised forms experienced on and off since the word was coined in the 17th century) offers nearly as many lessons as <i>The Art of War</i>, with the added advantage that we don’t need to read between the lines to work out how we’re expected to add in modern technology… our source materials are bang up to date (pardon the pun).</p><p>So what makes an effective terrorist? I suppose there are four factors that can be readily related to the world of technical communication.</p><dl><dt>Ideology and identity</dt>
<dd>Belief in an ideology is critical to the terrorist, and the ability to identify with others who espouse the same beliefs (although group membership is less important, some operate alone despite identifying with a particular group). Most technical communicators already fit this box (especially those who’ve joined something like the ISTC). We think of ourselves as technical communicators rather than just ‘people who write technical documents for money’. I’d pay attention to how someone describes themselves if recruiting for a mid-senior level position as they will be the source of indoctrination for others.</dd>
<dt>Part of the civilian population</dt>
<dd>Unless they’re posing for promotional photography, terrorists don’t wear a uniform. This cowardly unwillingness to paint targets on themselves is actually very useful when it comes to doing their job. Is that bloke digging next to the road to fix a broken sewage pipe, or plant a bomb? Who knows? But before it goes bang, he’ll have stopped for a coffee, changed his hat and be just another rushed commuter making a quick call to check his voicemail.</br>Similarly, a good technical communicator should blend into the team they’re supporting so that they’re in on all the conversations and able to gather the information they need to produce their content without wearing a target and getting in peoples’ faces. There should be trust involved in establishing the symbiotic relationship that technical communicators need with SMEs (subject matter experts) in order to get the job done.</dd>
<dt>Statement pieces</dt>
<dd>I’m not suggesting any of you blow up a building, kidnap an SME or imprison someone from a rival firm in a cage. However, I am suggesting that your products need to have a bit of something that makes them stand out whilst being identifiable to both you and your organisation. This can be done with logos and graphic design (see the black flag of ISIS), a style guide that’s both comprehensive and adventurous, and by getting the message out there through as many mediums as possible (there are many books still to be written on the ground-breaking ways modern criminal and terrorist organisations use social media and multi-platform multi-media messaging). It’s not always easy when you’ve been commissioned to write ‘a manual’, but clients and firms are usually comfortable with the idea of training materials running parallel to bundled documentation, and I’ve a couple at the moment who are really keen to use screen capture video as a way to reach an English-as-a-Second-Language client base.</dd>
<dt>Easily replaceable</dt>
<dd>In any organisation, aside from a few innovators and intellectual property holders, most people are replaceable. In a terrorist organisation, where a fair percentage at all levels of the organisation are being blown up on a regular basis (by themselves or their <i>competition</i>) this is doubly true.</br>I’ve worked with prescient clients who’ve brought me in because a (or <st>the</st>) SME is retiring and they need to capture and distil that person’s experience into a manual for the team he’s leaving behind. But I’ve also found myself in a firm when ‘the knowledge’ has already left and an expensive and time consuming reorganisation has become necessary. In both of these situations, I’m the agent of continuity.</br>If I have a pet hate, it’s being faced with a set of documentation and products where everyone, including the technical author, has been doing their own thing. It’s not a good way to work. I’d like to think that an equivalently qualified and skilled person could pick up where I’d left off should something untoward happen. Being consistent shouldn’t be that hard as modern technical communications software uses styles to control appearance and tags to indicate purpose, and our profession is filled with reasonably standard ways of working. Be mindful that if we’re responsible for continuity, accidents befalling us shouldn’t affect our replacement.</dd></dl><p>I suppose this goes to show that for the true professional, who’s always willing to learn, there are lessons tucked away in even the darkest corners of humanity.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-11193454518168690212014-09-29T14:44:00.002+01:002014-09-29T14:44:47.720+01:00Hail to the Chief!<p>I’ve been away with the Army Reserve for a couple of weeks, and it seems that things have been moving quite rapidly whilst I’ve been gone. Firstly there’s the start of Alison’s tenure as President of the Institute of Scientific and Technical Communicators. This is a voluntary position that Alison will hold for a few years as she juggles Clearly Stated with providing leadership and direction to the wider profession. Her first official engagement after becoming president at <a href="http://technicalcommunicationuk.com/">TCUK14</a> was an appearance on Radio 3’s <a href="http://www.bbc.co.uk/programmes/b04hyww6"><i>The Verb</i></a> where she talks about the importance of good technical communication in an ever changing world. The show is entertaining as Alison shares the floor with both a comedian and a poet in an exploratory discussion.</p><p>Now it would be nice to spill the beans about some of Alison’s plans for <strike>world domination</strike> the development of technical communication in the UK, but that would probably sit best in other forums (like her inaugural presidential article in <i>Communicator</i>) but it’s nice having a famous mum!</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-43957591285301779232014-08-26T15:43:00.000+01:002014-09-23T14:47:51.957+01:00Professional Memberships<p>I know I’ve been away from the blog again, as I’ve been busy. This hasn’t just been work (although that’s part of it), but in a wider professional sense. In recent months I’ve stepped up to full membership of the <a href=http://www.istc.org.uk/>ISTC</a>, and become a Fellow of <a href=http://www.itol.co.uk/uk/>ITOL</a>.</p><p>Today’s blog post can be read from a few distinct perspectives. Perhaps you’re a recent graduate wondering what all those extra post-nominals you see on business cards are for, or maybe you’re a peer thinking about joining or staying in a professional organisation. Then again you could be involved in running a professional body in some way, and you want to know what your members think. You’ll have to read between the lines a little bit – and this is very much my perspective – but I’m sure you’ll find something here of use.</p><p>It was tempting to create a series of tables and <i>infographic</i> you to death at this point in an attempt to compare various types of qualifications and professional bodies... but I’m afraid that if you want an answer to “what is chartered status?” or “what is a regulated profession?” you’ll have to head elsewhere. It suffices to say that the professional bodies I’m thinking of are those like the ISTC and ITOL where there is no qualification-based route to entry, and no statutory requirement to be a member (which means the same article written by a surveyor or surgeon about their professional memberships will reach somewhat different conclusions). Here are some of the things that you get – or <i>don’t</i> get – as a member of a professional body.</p><dl><dt>Validation</dt>
<dd>When you put in for membership of a professional body, you are scrutinised by a committee of Fellows (note the capital F) who are at the top of their profession. At the very least they’ll look at your CV and qualifications, and possibly a few samples of your work... they may also seek references. When they decide that you’re eligible for Membership, this means that you’re competent in the field, and when they opt to make you a Fellow, they’re acknowledging – for the record – that you’re at their level. For example, the team who decided to make me a Fellow of ITOL decided that I’m as capable a trainer and training consultant as they are – although we may train and consult in quite different specialist fields.</dd>
<dt>Confidence</dt>
<dd>With the status comes a bit of a confidence boost. I wouldn’t say that I've become a better trainer or communicator solely because of my memberships, but the validation has made me more confident. As a training planner, I’d occasionally run into situations where my plans were questioned and I was guilty of backing down and delivering a weaker solution as a result... but I now feel more resistant to those pressures.</dd>
<dt>Further Growth</dt>
<dd>Once you’re in a professional body, there’s the opportunity for further growth and development as part of that group. Those of you who keep up with my output will know that I regularly write for <a href=http://www.istc.org.uk/our-publications/communicator/><i>Communicator</i></a>, and this quarter I’ve used my involvement with the journal to get to interview one of my ‘heroes’ (this blog is spoiler free, so you’ll have to read <i>Communicator</i> to find out who this is). I’ve spoken at TCUK and roped one of my <a href=http://www.theguardian.com/profile/charlesarthur>favourite journalists</a> into being the keynote at last year’s conference – something I was sadly unable to capitalise on when it came to wrangling a writing gig!</dd>
<dt><strike>Jobs</strike> Contacts</dt>
<dd>While we’re on the subject of failing to capitalise on things, professional membership isn’t a route to getting a job (unless you happen to be in a regulated profession or require chartered status). Professional membership is a route to building your contacts and meeting the people who can guide you as your career develops, but unless you’re very lucky they’re not going to offer you a job. Similarly, unless you’re dealing with a company already very aware of the organisation, you’re unlikely to find membership as part of a job description... but you can still talk about it at interview as an example of how you’ve validated your professional practice, developed confidence and kept up to date.</dd></dl><p>So, I’ve become more “active as a professional”, which should hopefully lead to bigger and better things and I’ve learnt a little bit about professional bodies as a result. It’s good – in a warm and fuzzy way – to know that my work as a trainer and communicator (and indeed, trainer of communicators) is recognised and respected.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-18670193107266608142014-05-02T14:11:00.001+01:002014-05-02T14:23:41.334+01:00Saving a life<p>It’s not every day that something potentially life-changing happens. A few days ago, I’d been gone from work about 30 minutes when Alison got a 3-sentence phone call in which I identified myself, told her my location and instructed her to ‘come now’. When she arrived, I was shaking and covered quite liberally in blood (all of it belonging to someone else).</p><p>It had all started happily enough. I’d left work with the dog on her lead to go and collect the boy from nursery before heading home for whatever culinary delight was on the table. I was speaking to a potential client on the phone when an old lady in a wheelchair asked me if I’d call the police. As I hung up, I noticed that the children gathered around the old lady were scared of something. They asked me to ‘tell the police about the scary man near the swings’.</p><p>As someone else was able to make the call, I decided to wander a little closer towards the man as the children were obviously very frightened.</p><p>I must have been about 8 or 10 metres away from him when the side of one of the cars near him changed colour from white to <em>too-fast-red</em>. The guy stumbled a little then collapsed – and that was when I noticed the knife.</p><p>Finding the spot where that much bright, spurty blood had appeared from so quickly was vital, as it meant an arterial bleed... the kind that kills in minutes and seconds rather than sensible portions of hours and days. After taking his knife from him (in uniform you learn to disarm the casualty prior to treatment), I slid my hand up his sleeve to his upper arm. The blood was pulsing against my hand and no matter how hard I leant against the cut it wouldn’t stop. His jaw was slack, his eyes weren’t moving and his face was palid... but I knew he was still alive because of the flush-flush of blood against my palm.</p><p>By this time, an ambulance was on its way and a man asked if he could help. He took hold of my dog while I used her long canvas lead to wrap tightly around the arm until the bleeding slowed.</p><p>Sirens in the distance, then paramedics arrived to take over while two police officers arrive to do their bit with the knife, the public and any other fall-out. I can finally relax my grip after a really interesting bandage is applied that has a plastic cup fitted to one side, so that it places pressure into a puncture wound. Finally the guy’s on the stretcher, then in the ambulance being stabilised before the vehicle growls away with all the lights flashing.</p><p>The street is a mess. I realise just how much blood he’d lost...and how much of that had soaked into my clothes and skin. I gave my details to the officer, collected my dog, got into Alison’s waiting car and went – covered in blood and shaking – to collect the boy from his nursery.</p><p>Later the phone rings, and it’s the police to let me know that the man was rushed straight into surgery. Stopping – or at least slowing – the bleeding at the scene is probably what kept him alive.</p><p>I’m still jittery when I think about it, but I won that one. I’m a first aid instructor and an army reservist... but very little prepares you to deal with a casualty who’s inflicted such a horrid injury on themselves and is conflicted over whether they want to be saved.</p><p>I know this isn’t really a tech-comms posting, but somewhere I had encountered instructional materials that prepared me to do what I did today. They’d have been written by some long-dead scout master or an army surgeon, and they are memorable enough that when everything’s going crazy, the content comes to mind. Would your materials survive the ‘blood everywhere’ recall test?</p><p><span style="color: #3d85c6;">Andrew</span></p>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-11601096436679334302014-04-05T08:55:00.001+01:002014-04-05T09:32:15.014+01:00Limitations, empathy and accessibility<p>Yesterday I found myself curled in a ball on the floor of the gym surrounded by a pool of my own partially digested lunch. It wasn’t pretty, and was the result of trying to perform like a teenager whilst drastically under the weather. Through pushing myself, I’d found my limit, and upon making that discovery I didn’t want to do anything other than adopt the foetal position.</p>
<p>Why is a discussion of physical limitations important to technical communicators? Well, it comes down to how we prioritise and incorporate accessibility into documentation and therefore the products they support. By losing my lunch during physical training, I have some empathy for the individual whose mobility, stamina and coordination are at levels that mean they <em>have</em> to live in a bungalow, and find walking to the shops a herculean task… sure it’s a different thing they’re doing, but the end result of exhaustion, dizziness and curling into a ball on the floor are about the same. I’d suggest that a professional athlete is more likely to empathise with someone with a physical disability than a normal, unchallenged member of the public would.</p>
<p>We’re the pro-athletes of the communications world. We can produce copy, content and a whole gamut of useful and info-blurb on a variety of subjects. Worse, we often have these jobs because we have acquired various qualifications… proof that we’re super-sponges and masters at absorbing information. So how can we relate to the reader or end user who may be having to sound out each word, whilst repeatedly flicking between ‘the thing’ and the documentation about ‘the thing’ like a lost tourist? The answer is, most of us can’t innately empathise that way… we see the man in the mirror as ‘average’. We can’t ‘read till we’re sick’ to build the empathy, but there are things that we can do that may help:</p>
<dl>
<dt>Study something new</dt>
<dd>If you’re feeling smug and secure in your Engineering degree, go and learn poetry, or French, or even French poetry… if you’re more of a linguist, then why not try a course in mathematics or the physical sciences. The struggle you’ll have reprogramming your brain to ‘the new’ is what clients feel when the safety blanket of their old ways is yanked from them and that starting next week they’ll be using your firm’s solution.</dd>
<dt>Spend time in noisy places</dt>
<dd>I used to think I was good with noise… then we had a child, and I find that I now go to an artillery range to catch up on sleep. Turn the TV and radio on, grab yourself a copy of <em>War and Peace</em> and ask your partner to talk to you about shoes/football/North Korea. Imagine you’re going to have a quiz at the end of it all and you’ll have some idea of the pressure documentation and information can place on some people.</dd>
<dt>Wear sunglasses</dt>
<dd>Not when outside in the sunlight… but when inside reading a book, or using a screen. It’ll give you some insight into the importance of big, clear fonts with lots of white space on the page.</dd>
</dl>
<p>If you find your limits, you may have more empathy for those who are reaching theirs, and ultimately you’ll be willing to go the extra mile to make your work more accessible.</p>
<p><span style="color: #3d85c6;">Andrew</span></p>Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-16548246765394910942014-03-26T10:18:00.001+00:002014-03-26T13:09:49.760+00:00Gathering evidence...<p>It’s easy to say that you’re good at something. The difficult part is getting some hard evidence to back it up – especially when ‘the proof of the pudding is in the eating’ (in other words, you don’t really know until you’ve tried).</p><p>It’s a problem we’ve always had – many of our existing clients are reluctant to publicly acknowledge that we’ve done work for them, let alone share whether we’ve done it well or not.</p><p>We’ve been giving this problem some serious thought over the last few weeks, especially as we’ve been trying to promote our writing skills training courses a little more. We’ve managed to gather a few testimonials on LinkedIn, and (with permission) have posted them on our website as well. But that still leaves a huge gap.</p><p>Our credentials speak for themselves in terms of our writing (and other communication skills) – we publish some of our own stuff on our website, and we keep ourselves up-to-date. After a bit of investigating, we decided that the courses we offer fit best under the umbrella of ‘business skills’ and the most obvious place to look for more information was <a href="http://www.itol.org/">ITOL</a> (Institute of Learning and Occupational Training).</p><p>After a lot of hard work making sure everything was just as it should be, I joined the organisation as a member. (You need to be a member in order to have your courses accredited... but more than that, I felt I needed some validation of me as a trainer.) We then submitted samples of our materials, course overviews, details of course objectives and so on for scrutiny.</p><p>Success! All three of our core courses are now ITOL-accredited!</p><p>What does this mean? Well, we can point to an external source of verification that the methods we are using to teach are sound. It gives us a slight edge over some of our competitors. And if trainees want an official ITOL certificate, they can have one.</p><p>It also means that Andrew gets a few days in Slovenia. To become a member of ITOL himself, he needs to have completed an ITOL-accredited train-the-trainer course. I did the ‘<a href="http://www.blog.clearly-stated.co.uk/2012/11/wearing-different-hat.html">How to Become a Brain Friendly Trainer</a>’ myself a while ago, and that is an accredited course, so it seemed sensible to send Andrew to do the same... The next one is being <a href="http://howtobeabrainfriendlytrainer.com/slovenia/">run in Slovenia</a>. (I can highly recommend this course – it helps you think of some creative ways of training that drive away the monotony.)</p><p>What’s next? Well, now we’re accredited (which should help with the in-house courses we have been running for some time), we are going to run our first public open course in Nottingham on 18 June 2014. It’s a scary proposition in many ways. When we are commissioned to deliver a course in-house, we <em>know</em> the course is going ahead before we have to invest anything beyond a little time. With a public course, there will be the nervous wait to see what the uptake is like. Watch this space!</p><span style="color: #cc0000;">Alison</span>Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-13914880970436791592014-02-26T12:37:00.000+00:002014-02-26T12:37:31.908+00:00Talking to users<p>This week I’ve been preparing Captivate videos with voiceovers for a client. It’s a task I particularly enjoy, and wish that more clients would request this kind of service. I think adding sound to training materials is brilliant for accessibility reasons, as well as improving the customer engagement with what can otherwise be very dry texts. You may be thinking of producing something similar in your organisation, so here are a few tips:</p><dl><dt>Learn the tools</dt>
<dd>Preparing a good software simulation or e-learning experience is a very different task to writing a manual or online help file. I see a lot of adverts out there for technical communication roles where <i>Captivate</i> is thrown in on the same list as <i>Word</i>. Captivate is excellent software, but in terms of complexity it sits somewhere between PowerPoint and the high end production software used to make movies. It’s relatively easy to learn, but tricky to master, and the difference will show in your final products. Help is at hand with some very nice <a href="http://www.adobe.com/cfusion/event/index.cfm?event=list&loc=en_us&type=ondemand_seminar&product=Captivate&interest=&audience=">on-demand training from Adobe</a>, but nothing beats a bit of practice.
<dt>Choose a voice - watch the Simpsons!</dt>
<dd>If you don’t know the show, listen to a few episodes of the Simpsons before voicing training material... it’s an excellent guide to the non-verbal qualities we hear when people speak. When doing voiceovers, I’m always tempted to channel <a href="http://en.wikipedia.org/wiki/Troy_McClure">Troy McClure</a>; the character famous for introducing himself at the start of his segments with comments like “Hi, I'm Troy McClure, you may remember me from such instructional videos as <i>Mothballing Your Battleship</i> and <i>Dig Your Own Grave and Save</i>”. I’m not talking about dropping in my own name, or having some other semi-comedic catch phrase. However, choosing Troy’s confident, paced timbre over Crusty’s manic laugh, Homer’s grunts, or any of the accent-heavy, metaphor-rich, and confusing dialogue we find from Willie, Apu, Mo or Bart pays off. Accents are a wonderful sign of the breadth of the English language, but if you’re constantly frustrated by automated telephone systems failing to understand you, then you might want to consider finding a colleague to read your script. Back up your planned voice with a nice microphone and <a href="http://audacity.sourceforge.net/">Audacity</a> and you’re good to go.
<dt>Have a conversation, with pauses</dt>
<dd>If users were able to cope with a deluge of information, they wouldn’t have started the training video in the first place. The last thing they want is more self-loathing because they can’t execute the steps fast enough to keep up with you. The lazy solution to this is to put a loop into the video so that they see and hear everything twice, in the hope that you’ll catch them the second time round. What I prefer is to have a more natural conversation with the user that includes details from the user case I’ve generated... so when documenting a course management platform, I’ll include information that may not make it into the manual, like the reasons an experienced teacher would choose to set certain genres of reading assignments, to give the user time to catch up with the on-screen steps.</dd></dl><p>A good tutorial video has many uses, it becomes business-wide content that can be streamed to the TV in the reception area, used by the marketing team at client presentations and trade fairs... most importantly it gives a real alternative to the written manual for users with accessibility issues or a paucity of time. If you’ve had any experiences (good or bad) with training videos and e-learning content, feel free to share in the comments below.</p><span style="color: #3d85c6;">Andrew</span><br />
Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com1tag:blogger.com,1999:blog-4230806855799860566.post-66398308663341205282014-02-17T16:50:00.000+00:002014-02-26T09:47:36.126+00:00Intentionally bad<p>Have you ever encountered tasks or subjects that are are written about so badly or sparsely, you get the impression that it’s been done on purpose? I can think of two topic areas where the documentation fits this description together with some pretty good reasons why.</p><dl><dt>Gunpowder, treason and plot</dt>
<dd>Most people know the composition of gunpowder and the ratios of the mix aren’t too hard to come by. If you watch the news you probably have a reasonable idea of what goes into home-made high explosives... but that’s as far as it goes. Most descriptions of anything that goes “bang” are <a href="http://www.amazon.co.uk/Chemistry-Explosives-Jacqueline-Akhavan/dp/1849733309/ref=sr_1_1?s=books&ie=UTF8&qid=1392654760&sr=1-1&keywords=explosives">curiously short of a step by step guide to manufacture</a>, whilst the literature that does exist seems subject to a campaign of nay-saying and warnings of disaster. The reason (of course) is that those of us who understand how these things are made would rather people who shouldn’t have explosives blew themselves up in their own garden shed when getting it wrong.</dd>
<dt>Hacking</dt>
<dd>Hacking is performed much like any advanced task on a computer. It’s not <i>The Matrix</i>, often it’s just a case of <a href="https://www.udemy.com/blog/sql-injection-tutorial/">putting the right bits of SQL</a> into a box on a webpage or working out that email addresses in a company follow a pattern (such as <code>[firstname].[lastname]</code>) and going through their login page one employee at a time to find the dude who’s been allowed to use <code>123456</code> or <code>password</code> for their login credentials. In a less than ideal world, <code>admin@[company].com</code> with an obvious password will exist with all the implied access. More advanced hacking (the kind that makes the newspapers) requires detailed knowledge of exploits and weaknesses in systems (that I don’t have) which are painstakingly researched and <a href="http://www.computerworld.com/s/article/9241585/XP_s_retirement_will_be_hacker_heaven">closely guarded secrets</a>. Often <a href="https://www.udemy.com/blog/sql-injection-tutorial/">tutorials on hacking</a> stop just short of allowing the reader to do any damage, whilst most of what happens has no easily accessible knowledge base as it would allow software companies to conduct a bit of counter research and fix their products.</dd></dl><div class="separator" style="clear: both; text-align: center;"><a href="http://3.bp.blogspot.com/-vwjyuHElPK4/UwI_H-pxWtI/AAAAAAAAAMk/-wQEXGTdvhY/s1600/bigstock-Information-grenade-22247999.jpg" imageanchor="1" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" src="http://3.bp.blogspot.com/-vwjyuHElPK4/UwI_H-pxWtI/AAAAAAAAAMk/-wQEXGTdvhY/s200/bigstock-Information-grenade-22247999.jpg" /></a></div><p>What are the implications for technical communicators from these two nefarious examples? Well, firstly, there is a rebuttal to the school of thought that says “share everything, and put it on the web“ – anything that gets released out the door should be vetted so that it doesn’t give away commercially sensitive details or allow harm to come to the organisation and its customers – this includes the habit that some software providers have of publishing their default admin account details and passwords in manuals available in soft-copy form without reminding (or forcing) their customers to change them. Somewhere, a customer will place these documents on an unsecured intranet, and that will open up a vulnerability for every client you have who hasn’t bothered removing or changing the default account settings.</p><p>Secondly, there’s the social proof provided by these well known examples... if products don’t have documentation, or if documentation is incomplete, there is a risk of damaging reputation because clients will identify the product with the dodgy, and one way or another they’ll trust you less than they should.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-47914063248623659852014-01-30T15:54:00.001+00:002014-02-03T13:18:40.447+00:00New devices, alien worlds<p>I wrote earlier about the way in which <a href="http://www.blog.clearly-stated.co.uk/2013/01/new-year-tech.html">new devices with curved, round or irregular shaped displays</a> would need new standards and vocabulary in order to describe the interactions with those screens and surfaces, partly because those surfaces are likely to be touch sensitive. It’s not an insurmountable problem, and the biggest issue may well be the politics involved in getting professionals from a variety of manufacturers and background’s to agree. That being said, there are authors who’ve developed a lot of time and thought to the description of novel geometries and I’d like to think that when standards committees meet, they’re going to channel some of the greats of science fiction.</p><dl><dt>Disc shaped, or round screens</dt>
<dd>An “always up”, round screen would make a lot of sense for tablets of the future (if Apple are reading this, I’d quite like royalties). We’d have to get used to seeing web-pages cut or scaled in interesting ways, but for many other applications including games and creative apps, there would be many advantages (not least because our eyes are “round” and much of our visual field is wasted with traditional screens). For movements around the screen or involving rotating, we have clockwise and anti-clockwise to fall back on, but what about moving to and from the centre of the screen. Perhaps the best known vocabulary for describing a surface of this type is found in <a href="http://www.terrypratchettbooks.com/">the work of Terry Pratchett</a> who coined four cardinal directions of “Hubward”, “Rimward”, “Turnwise” and “Widershins” to describe navigation on his Discworld. Turnwise and Widershins only really work for a disc already in motion, but hubward and rimward are the words we’re going to need the day we get an iDisc.</dd>
<dt>Rings, bracelets and wearable tech</dt>
<dd>As we start to see devices like the <a href=http://smartyring.com/>Smarty Ring</a>, become more popular we’re going to be looking at <a href="http://www.dcs.gla.ac.uk/~stephen/papers/IEE_wearables%20_00.pdf">non-visual interfaces</a> that work with touch, motion or other forms of manipulation (the link here is to an excellent paper from the University of Glasgow... it’s well worth a look as it gives a good summary of what can be done and isn’t trying to sell anything). Describing the control of such a devices is going to be tricky, in part because the device can rotate around the arm, as well as being touched or manipulated by the voice. I couldn’t really find anything that worked for touch sensitive bands in professional or academic literature but an answer comes, yet again, from a fictional world. This time we turn to <a href="http://www.halopedia.org/Halo:_Primordium">Greg Bear and his writing set in the fictional Halo universe</a>. He uses turnwise and crosswise to describe movements around and across a band respectively and this could work when coupled with “left”, “right”, “clockwise” and “anticlockwise”. I initially toyed with the idea of using the geometry and layout of the human body to help with the descriptions, but realised that these devices may be worn on either arm by left or right handed.</dd>
<dt>Projected space</dt>
<dd>By projected space, I mean 3D environments created by devices such as Kinect, Google Glass, and the very <a href="https://www.leapmotion.com/"><i>Minority Report</i>-esque Leap Motion controller</a>. I feel that many of these systems will be dictated by the intent and application of the software and hardware being used, but it’s quite obvious that any directions being given will need a reference point. An example of this being done well can be found in the work of <a href=http://www.johnghemry.com/>John G Hemry</a> who tells tales of wars in space together with a spatial reference system he’s thought out that allows for ships to quickly orientate themselves in the 3D environment of a new solar system. Documenting a system that relies on the body for imput would not just need a way to describe the like this may well not look forward at all, as what we’re really talking about is whole body movement. The language and presentation of the documentation may borrow heavily from descriptions of other physical movements, whether that be those found in <a href="http://www.blog.clearly-stated.co.uk/2013/06/freeze-frame-violence.html">martial arts text books</a>, reference works on magic tricks or even the <a href="http://www.sacred-texts.com/sex/kama/">Karma Sutra</a>.</dd></dl><p>Answers on a postcard (or in the comments section) for what you think the biggest new interface will be, and how we could go about describing it.</p><span style="color: #3d85c6;">Andrew</span> Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-28103272046033008672014-01-27T16:30:00.000+00:002014-02-10T07:26:34.396+00:00That was the year that was...<p>Thirteen is considered by some to be an unlucky number, so my first thought as I settled down to write was to wonder why. After a few minutes of pleasurable distraction (what <em>did</em> we do before search engines?), I’ve discovered that there are a lot of theories but no hard evidence to support one over another. So how was 2013 for us, good or bad?</p><p>Well, as with every small business, we’ve had our ups and downs – sometimes exacerbated by the fact that a family crisis (no matter how small) tends to affect <em>every</em> member of the business when you’re the <em>same</em> family! I’m not going to dwell on the negative, though... there isn’t a lot of that, and I’d much rather focus on the positive.</p><p>So, what happened in our world in 2013? Quite a lot, now I come to think of it! In no particular order:</p><ul><li><b>We changed the legal status of our business</b> – we activated Clearly Stated Limited on 1 November 2013. The company had existed since Clearly Stated started, back in 2004, but had been dormant as until recently the advantages of trading as a company were negated by the extra administrative burden. Now, however, we are beginning to spread our wings a little, and the change in status fits with where we see ourselves going in the future.</li>
<li><b>We presented at TCUK 2013</b> – both Andrew and I delivered sessions at our <a href="http://www.technicalcommunicationuk.com/">professional body’s annual conference</a>, and both were well received.</li>
<li><b>We delivered more writing skills training courses</b> – both to local authorities and at a university.</li>
<li><b>I dusted off my clinical knowledge</b> to work on a health-related application.</li>
<li><b>We received a SaBRE Certificate</b> which acknowledges Clearly Stated's support of Andrew's reserve service.</li>
<li><b>I developed a CPD framework</b> for the ISTC.</li>
<li><b>Andrew passed his first module</b> on the Graduate Certificate in Technical Writing with the University of Limerick.</li>
</ul><p>All things considered, that’s a pretty good year. 2014 is already shaping up quite nicely. We’ve made contact with a few people we’re looking forward to working with and are already planning conference attendance and milestones for the next phase of our development.</p><span style="color: #cc0000;">Alison</span><br />
Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com1tag:blogger.com,1999:blog-4230806855799860566.post-70367072835354756882013-12-18T10:10:00.000+00:002013-12-18T10:11:45.271+00:00Keeping up-to-date...<p>Things change so fast in our field (technical communication) that it can be difficult to keep up. What can be even more difficult is providing some evidence that you’re at least making the effort. That’s why I’m pleased that the ISTC’s <a href="http://www.istc.org.uk/training-education/continuing-professional-development/" title="CPD framework">CPD framework</a> is finally up and running. (I’m also pleased because getting it to this stage has taken an inordinate amount of my time over the last 18 months.)</p>
<p>So, aside from getting my life back, why am I so pleased?</p>
<p>Well, in line (I guess) with just about anyone who takes what they do seriously and want to do it to the best of their abilities, I am constantly learning. I don’t mean I’m constantly attending training courses – although I do some of that too – but that I work on a different project, find out how to use a new tool, come across a technique that someone shares... and I find I’ve learnt something really useful.</p>
<p>My problem, until now, was that although I knew I’d learnt lots of good ‘stuff’, put on the spot in an interview or when writing a covering letter for a job, I couldn’t always remember what I’d learnt when, or what the context was at the time. In short, I couldn’t tell a coherent story to support my application.</p>
<p>Now that’s not a problem.</p>
<p>I’m a Fellow of the ISTC myself – and although all our members have a requirement to keep up-to-date, I can now prove it. I have to maintain a CPD record to keep my Fellow status, which makes it all the more valuable to me.</p>
<p>And having to keep a record means that the information that was previously just swimming around in my head and had been absorbed into ‘normal working practice’ can now be accessed as discrete pieces of information and referenced.</p>
<p>You know what it’s like – you’re writing a covering letter to apply for a contract and you’re desperately trying to think how you can show you’ve met a particular requirement. Now instead of frantically trying to remember, I can just have a quick glance at my learning record instead.</p>
<p>Couldn’t I have recorded this anyway? Well, to be honest, I often did... but not to the same level, as it was only notes for my own use. Now there is a little more meat on the bones.</p>
<p>If I want to think of myself as a professional (and more importantly want others to do so), I need to start acting like one.</p>
<span style="color: #cc0000;">Alison</span>Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-34932880071598621212013-11-27T13:20:00.001+00:002013-11-27T13:20:55.568+00:00Mixed Messages<p>I don’t usually touch on politics in my blog posts – I believe it’s against policy – but I was struck by a recent article where our illustrious PM decided to link <a href="http://www.theguardian.com/politics/2013/oct/28/david-cameron-education-migration-factories">the quality of state education with the inability of many to find a entry level job on a production line</a>. As a technical communicator, I think he’s wrong. My reasoning is based both on my own experiences in education and training, and my current professional practice.</p><p>I remember preparing for my GCSE English exams. Our English teacher received a missive from the exam board on the subject of ‘structured writing’. There was a whole section on the types of phrases we could use to compare and contrast arguments and introduce points of view, which our teacher dutifully read out to us. They became more florid the further into the list you progressed, perhaps reflecting the fact that a lower-grade student would only be expected to remember the first few. Right at the end was “there is a train of thought that runs...” – by this point the class was in hysterics. There was something about the way that our teacher chose to read that list that let us know it wasn’t to be taken too seriously. She finished with the staunch admonition that were we ever to use such a convoluted phrase to convey “others think...” she would hunt us down one by one.</p><p>There is, however, a train of thought that runs to the acceptance of such phrasing (it has taken me 15 years to work that into a piece of writing with an almost straight face). The people who hold this view were taught by the other type of English teacher: the ones who didn’t laugh and snigger at the directives being sent down from those who view having an education as having the ability to show off (or as it is called in the north of England, ‘ponce about’). The adherents of this doctrine write as floridly, passively and with as many synonyms thrown in as possible because they have been taught that this is how the educated communicate. (If you don't believe me, watch <a href="http://www.parliament.uk/business/news/parliament-government-and-politics/parliament/prime-ministers-questions/">the tortuous pursuit of definition that is Prime Minister's Questions</a>.)</p><p>Of course, this is how the ‘educated‘ tend to communicate. Lead engineers, managers, and those at CxO level (where x is some function of the business) generally communicate from within their own comfort zone, blissfully unaware that to those outside their circle they may as well be using a foreign language. The manager states “we must be flexible with regards to the future” when planning layoffs; meanwhile the employee is wondering when the new yoga classes are going to start. In another example, the lead design engineer has referred to the same binary function selector as a switch, toggle, selector and lever interchangeably within a single paragraph of emergency shut-down instructions... that are being read whilst the machine in question trundles towards a cliff edge. Both examples mirror political communication a little too well.</p><p>The real problem is that job seekers don't know exactly what they need to do to get the job they want because they aren't told in a way they understand. Therefore, the issue is not in the education and training of the many, but the education of the few who think their communications strategy is fit for purpose when attempting to get a message across different levels in society, organisations and processes. In many cases the problem lies with message and sender, not the befuddled receiver. This gap is why technical communicators exist. We work with subject matter experts and transform their message into something that the end user can understand.</p><p>Whilst my services as a professional communicator are a valuable commodity, I feel that on this occasion I can distil 25 years of experience as a learner, teacher and technical communicator to help the Prime Minister and anyone else who fancies being a politician or leader of men avoid some often identified pitfalls.</p><dl><dt>Answer the question being asked</dt>
<dd>You may be a leading expert on a particular subject, but when someone asks “what happens if I press the big red button?” your answer should go along the lines of “when you press the big red button, X happens.” Your audience do not want to know about why you think red is a nice colour, why X is such a favourable outcome, or how brilliant you were in suggesting to a colleague that they have their secretary open a bidding process to pay a large company – run by a family friend – to subcontract an electrician to install the big red button.</dd>
<dt>Think about the context of the recipient</dt>
<dd>I have an emergency bandage. The instructions are in 5 steps. Steps 1 to 4 deal with applying the bandage, and consist of big clear illustrations that can be read under a torch in low light. Step 5 deals with removing the bandage and consists of black text on a grey background. The pictures exist because when your mate is bleeding to death at 2 in the morning, you don't have time to read an essay. There are people in society who – for whatever reason – are bleeding out and are relying on you and your team to get the job done, and they really don't have time for anyone to wade through verbiage.</dd>
<dt>Short words are the best</dt>
<dd>This pithy piece of tech-comms wisdom stems from one of your predecessors, but it is true. I'd suggest that "yes" and "no" are two of the short words that might come in useful for answering questions. If people want your life-story or to know what you've been thinking about recently they can call you "Dave" and add you on Facebook.</dd>
<span style="color: #3d85c6;">Andrew</span></dd></dl>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-21812444578902837502013-07-09T16:48:00.001+01:002013-07-09T16:49:21.794+01:00We have ways of making you think!<p>A good friend of mine is a developer at <a href="http://www.north-51.com/">North 51</a>. Recently we had an interesting discussion about mind control. Not the type of mind control that would let me unleash hordes of hypno-zombies as a tranced and swaying flash-mob at the local Tesco (although having sacrificed last Sunday morning in that edifice of consumerism, I’m not entirely sure someone hasn’t already pulled this off), but rather the kind of mind control that would let me think my pointer across the screen, or these words onto the page.</p><div class="separator" style="clear: both; text-align: center;"><a href="http://1.bp.blogspot.com/-pUkoHNEr6n8/UdwsCsKCLyI/AAAAAAAAALw/5B5gZtU1vh0/s1600/bigstock-A-Beautiful-Woman-Manikin-With-13346198.jpg" imageanchor="1" style="clear: left; float: left; margin-bottom: 1em; margin-right: 1em;"><img border="0" src="http://1.bp.blogspot.com/-pUkoHNEr6n8/UdwsCsKCLyI/AAAAAAAAALw/5B5gZtU1vh0/s200/bigstock-A-Beautiful-Woman-Manikin-With-13346198.jpg" /></a></div><p>Whilst even this seems far fetched, headsets like the one pictured here let people <a href="http://www.youtube.com/watch?feature=player_embedded&v=WDgkZZYSVPo#at=48">play Angry Birds with just the power of their minds</a>. Angry Birds is a fairly simple game, essentially involving the movement of a mouse/pointer and a single click or dragging action (depending on whether you are playing on a PC or a tablet). The fact that the description of the game varies between a tablet and a PC gives some idea of the issues we might face when giving instructions for a user whose interface is their own mind. The cursor in Angry Birds (PC) is a hand, so are people playing the game thinking “I’ll move the mouse around with my hand” or “I’ll move the hand around with my mouse” or even “I’ll move the hand around with my hand via the mouse” (think of your own variant). Any guidance for play-by-brain computing not only has to account for these differences when describing the desired end result but must also cover the thought processes that are involved in reaching it. I have been thinking about how this could work in practice:</p><dl><dt>You are feeling sleepy</dt>
<dd>Instructional materials could use techniques from the relaxation or hynotherapy fields to induce a non-cluttered state of mind before operating the game/robot surgeon/share dealing platform. This is not really a new idea. Educators have been springboarding off the work of Soviet scientist <a href="http://en.wikipedia.org/wiki/Georgi_Lozanov">Georgi Lozanov</a> to create non-threatening, trance-like language classes filled with baroque music and a brain boosting vibe for decades now, and there’s no reason it could not be coming to technical documentation near you soon.</dd>
<dt>Enter the Sandman</dt>
<dd>Sandbox environments are big in the gaming community, and as documentation gets increasingly gamified there’s a lot to be said for blurring the line between the real situation and a simulation. (Pilots do this already, the theory being that in a simulator no-one can hear the passengers screaming, praying or bouncing off the walls.) <a href="http://www.yukaichou.com/gamification-examples/octalysis-complete-gamification-framework/">Yu-kai Chou</a> divides gamification into White Hat (nice) and Black Hat (bad) gamification. A nice happy sandbox environment with all the tips, hints and lessons being presented in a calming and constructive way would blend the best of usability with the logic of well-written instructions and a little bit of Zen.</dd></dl><p>The future is probably a lot closer than you think on this one, so I’d be really interested to hear from any others (technical communicators or otherwise) who’ve given this fascinating field a bit of thought.<p><span style="color: #3d85c6;">Andrew</span><br />
Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-42186834962587310342013-06-18T11:00:00.003+01:002013-07-04T14:56:49.951+01:00Freeze frame violence<p>My first degree (back when I could afford to study out of interest) was Theology and Religious Studies. I’d told people I was studying this subject because I wanted to be a diplomat, but a big part of it was the traces that previous iterations of civilisation have left scratched, carved and drawn in the world. Look at many temples, or even cave paintings, and the depiction you find is often of violence. It might be a Hanuman carving of a battle against demonic forces (Thailand), a beheading (the Sistine Chapel, Rome) or arrows being launched at galloping animals (cave paintings, France). These artistic portrayals of violence are reminiscent of the rapid cuts and flashes seen in the fight scenes of <a href="http://www.unc.edu/~slindsey/">Raging Bull</a> where the freeze frame is chosen as the most dramatic and telling part of the whole physical sequence.</p><div class="separator" style="clear: both; text-align: center;"><a href="http://1.bp.blogspot.com/-tuAxcclTe30/UcAs8S_PnnI/AAAAAAAAALI/nkO9fjDOz9U/s1600/aikido.jpg" imageanchor="1" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" src="http://1.bp.blogspot.com/-tuAxcclTe30/UcAs8S_PnnI/AAAAAAAAALI/nkO9fjDOz9U/s200/aikido.jpg" /></a></div><p>This was particularly fascinating to me as I’ve always studied some form of martial art. First it was Karate, then fencing at university (I even won a medal for that one), then Mongolian wrestling in China, Taikwondo with the air force in Oman, and most recently boxing. All of these come with books of some description that in many ways mirror their artistic counterparts in that they freeze the action at the most telling moment. An example from an early Aikido manual is given here. In this picture the combatant on the right is defending himself against an armed aggressor. The scene is frozen at the moment of impact. Artistically this is all well and good, but what else can we see from this image that is of use for technical authors?</p><dl><dt>Capture the moment of impact</dt>
<dd>I’m reminded of a style guide I recently encountered that stated “When accompanying an instruction with a screenshot, the mouse pointer should be displayed carrying out the task.” In this case the mouse pointer is the right hand as it strikes below the chin.
<dt>Decide on sensible minimalism</dt>
<dd>The defender has stepped in with his left leg and lowered his centre of gravity to make himself more difficult to engage with a long bladed weapon. This is shown without any real need for explanation as any martial artist will tell you, footwork eventually becomes reflex. In the same way there are things that we don’t bother to screenshot or explain in great detail as we assume that if the end user cannot turn their PC on, they’d hardly be reading the manual for a complex system.</dd>
<dt>Establish documentary conventions for important details</dt>
<dd>In this drawing, our defender has a single finger hooked at the waist of his attacker to off-balance and drag the swordsman forward onto his strike. This is artistic emphasis: the actual move requires a handful of belt, clothing and man to be grabbed in a fist and bodily hauled towards the defender, but when drawn this would look too much like a second fist striking the target and so the single hooked finger is drawn to emphasis the pulling action. This and other stylistic elements are found again and again in hand drawn martial arts manuals. They are not dissimilar to the refined vocabulary used to describe on-screen processes (interestingly the cursor sometimes morphs into a hand with a single extended digit to reflect an action in much the same way).</dd></dl><p>Revisiting the Sistine Chapel, we see Goliath’s final moment captured. As anyone who’s ever chopped wood or swung a hammer will tell you, the moment to get right is the top of the swing when all the force and balance and energy is about to be released. David is exemplary: his shoulder is cocked, his wrist open and his whole trunk unwound ready to deliver the blow. Goliath is as good as dead, as if the blade had already completed its gore-punctuated descent. As technical authors, we should aim to capture this exemplary and telling moment as well as the final static outcome in what we write and display.</p><span style="color: #3d85c6;">Andrew</span><br />
<br />
Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-70784406657727596832013-06-17T16:35:00.003+01:002013-06-18T17:19:50.022+01:00TCUK 2013: A two session preview<p>We’ve had some good news at Clearly Stated this week. We are both going to be presenting at <a href="http://www.technicalcommunicationuk.com/" target="_blank">TCUK</a> in Bristol, which reflects well on our dedication to not only our own development as technical communicators, but the development of technical communication.</p>
<p>For those of you who are interested, we’re offering a slightly more in-depth sneak peak of our sessions at the conference. There is no need for a spoiler alert, but hopefully a bit more insight into the presentations will helps peers reading this blog choose their session at the conference.</p>
<dl>
<dt>When Culture Meets Content (Andrew’s session)</dt>
<dd>My first role as an author was creating training materials and designing courses for the Royal Air Force of Oman. This presented unique challenges together with the possibility to conduct research. The audience for these materials and courses were entirely male, Omani and Muslim, and I quickly began to notice that the reaction to materials (either my own or commercially published materials) was coloured by the cultural perspective of the students. Through a comparative study, I set out to explore some of the issues documentation and training materials face when being viewed through the middle eastern cultural lens. It is important to note that many of the cultures that are sensitised in some way to the perceived morality of documentation also favour indirect communication and value face. Many of the lessons learnt may help those wishing to position their documentation and services to avoid faux pas.</dd>
<dt>Managing as a freelance technical communicator (Alison’s session)</dt>
<dd>‘Managing’ often conjures up images of project plans, performance appraisals and (of course) meetings. Depending on the size of the organisation, one person may fulfil more than one role (as both a project manager and a people manager, for example) but nowhere do the hats pile as high on one head as when running your own small business. Since I started Clearly Stated, I’ve had to manage my workload, my finances (including estimating and quoting), my clients and my employee – and find time to actually do the work I’m being paid to do! The intention is for you to learn from my mistakes, helping you to work smarter, not harder.</dd> </dl>
<p>We look forward to seeing you there.</p>
Andrew and AlisonAndrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-4177042687921698112013-05-16T07:58:00.000+01:002013-05-16T09:13:19.749+01:00Learning by sharing<a href="http://2.bp.blogspot.com/-pt4bvq2nbxs/UZSBHV7w-aI/AAAAAAAAAGA/HCRwoVKSOF8/s1600/Learn.png" imageanchor="1" ><img border="0" src="http://2.bp.blogspot.com/-pt4bvq2nbxs/UZSBHV7w-aI/AAAAAAAAAGA/HCRwoVKSOF8/s320/Learn.png" alt="Two hands holding a ball covered in words relating to learning" align="right"/></a><p>I’m in! I’ve received my ‘proposal accepted’ email from the organisers of TCUK (<a href="http://www.technicalcommunicationuk.com/" title="The Technical Communication UK website" target="_blank">Technical Communication UK</a> – the annual conference for anyone in my field in the UK) and I will be delivering a session on ‘Managing as a freelance technical communicator’.</p>
<p>I'm really looking forward to it, and have between now and mid-September to work out exactly what my message is, how I'm going to deliver it, and how I'm going to learn from the other people in the room.</p>
<p>Wait a minute... learn from the other people in the room? What’s going on – aren’t I the one supposed to be sharing knowledge? Well, this will be the fourth time I’ve presented at this conference (and its predecessor) – and each time I’m sure I’ve learnt at least as much from the experience as those who attended the sessions.</p>
<p>The first session (in 2008) was co-presented with Alison Reeves (of <a href="http://writetowin.co.uk/wp/" title="Write to Win website" target="_blank">Write to Win</a>). We did a 3-hour (yes, 3-hour) workshop on advanced techniques in Microsoft Word. Alison came to see me before the conference so we could work out who was doing what, and when. I lost count of the times one or the other of us would say, “How did you do that? Do it again... slowly.” We'd both been using Word for years – but we learnt a lot from each other that day.</p>
<p>Last year my session was on CPD (Continuous Professional Development, which some of you may know as CPE or Continuous Professional Education). I incorporated an exercise where people in the room discussed various activities and decided whether – and under what circumstances – they were valid CPD activities. Watching people discussing the options, coming to conclusions, arguing, changing their minds and challenging others opened my eyes to a much wider range of possibilities than the already-wide range I’d had in mind.</p>
<p>It's not just restricted to conferences – I teach writing skills, and am a tutor with the Open University, and it’s rare for me not to experience a fresh perspective at some point during a session.</p>
<p>TCUK is a fantastic learning experience even when I’m not presenting (which is the main reason I go – see '<a href="http://technicalcommunicationuk.com/index.php/archives/719">Why you should attend TCUK 2013 - a personal perspective</a>'). It’s also a great opportunity to catch up with others in my profession... the life of a freelance technical communicator can be somewhat isolating, even now there are two of us. If you are involved in technical communication, we’d love to see you in Bristol!</p> <span style="color: #cc0000;">Alison</span>Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-84683255011876445572013-04-29T15:17:00.001+01:002013-05-04T16:56:58.546+01:00The Infinite Monkeys Approach<p>I once knew an expatriate worker in the Far East who was tasked with liaising with the office cleaners because he could “speak the language”. In theory this was a good idea. However, the cleaners were all profoundly deaf, so whoever got the job was going to have to learn or invent a sign language before they could begin, whatever languages they currently spoke. The assumption of competence being granted because of linguistic faculty is sometimes amusing when it happens in a second language (I ‘speak’ Mandarin, but that doesn’t mean I can quickly and easily understand a lecture about orthopaedic surgery in the language; I’d struggle to keep up with that topic even in English), but from a professional communicator’s point of view it is even more irritating when it's done in the workplace with technical documentation.</p><p>Recently I’ve been seeing some particularly bad examples of documentation. The kind of stuff that is so bad that it has passed the point of irritating users and is actively dissuading potential customers. What did it have in common? It was written by ‘experts’ – in the topic, not in communication. I wonder why it gets written like this, particularly when the time of specialist developers and engineers is taken away from their core duties to produce it.</p><p>What shocks me is that businesses already know that their geeks often work best when kept away from customers. It’s why they employ sales people to do the verbal communication that brings in sales... because customers want to hear about software meeting their requirements, not how cool the software is because the subroutines are all named after characters from Star Trek, deceased pets or steam trains.</p><p>I've also heard of ‘test’ entries into database products that have made their way into training and documentation materials, and even into the finished product. Sometimes these just hinder understanding (“test for empty field” isn't a good example to follow), whilst others can cause offence (“nutty as a fruitcake” as a mental health condition for example). </p><p>This criticism is not directed at developers, they do a job I couldn't do, and they do it well. It's directed at the person who decides that because their developers happen to speak English, they're going to save money and give them the documentation to write. As an approach to documentation management this is only marginally better than handing infinite monkeys, infinite typewriters (and marginally cheaper due to the resultant cost of infinite bananas).</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-25659174458166778952013-03-22T17:22:00.000+00:002013-03-30T07:06:37.804+00:00The Underground<p>Academics, especially the non-scientists, often face the criticism that they have an aloof existence in ivory towers. An easily recollected if ill-favoured example is academic and author H.G. Widdowson who in his book <cite>Practical Stylistics</cite> has the unfortunate habit of calling non-canonical poems “dogrel”; even when they’ve been written effectively and serve their intended audience well, and especially when they’ve been written in memory of departed relatives. This blindness to, and denigration of, changes in a field weakens not the target of the dismissal and contempt, but the person making the aspersions (which is why traditionalist generals lost out to Germans with panzers and a remarkably modern air force during the early years of WWII). With this in mind this week’s blog is a bit of a walk on the wild side, because out there in cyberspace there are thousands of amateur technical communicators doing very interesting things, sometimes approximating the tools we use, and sometimes innovating to get their message across.</p><p>First up there’s YouTube and the ubiquitous video demonstration; the most popular result for the search terms “how to” come from <a href="http://www.youtube.com/user/HouseholdHacker">Household Hacker</a> and run from an introduction to <a href="http://www.youtube.com/watch?v=vsQh1AT6qUE">the manufacture (at home) of a magnetically responsive liquid</a> to the creation of a <a href="http://www.youtube.com/watch?v=3oa7ifmHm4U&list=UUI4I6ldZ0jWe7vXpUVeVcpg&index=3">candle powered space heater</a>. The presenter uses a variety of camera angles and captions to get his message across, and succeeds in presenting easily reproducible experiments and activities to end users. Whilst he’s not using the latest and greatest technical communications software, he achieves his aims in a way that would make any technical communicator feel it’s a job well done.</p><p>Those of us who spend our time writing rather than getting to create video tutorials may feel that there’s less competition from amateur authors, but it does exist for some fairly commonly used software packages. Of course by “commonly used software packages” I’m talking about video games! There are entire communities of gamers on-line who dedicate hours of their lives to documenting the solutions and tricks that go into beating their favourite games. <a href="http://www.motthoos.com/">Matt Hughes</a> writes guides to <a href="http://www.gamesradar.com/xcom-enemy-unknown-classes-and-abilities-guide/">killing (virtual) aliens</a> that are detailed, entertaining AND in line with best-practice in software documentation whilst gamer community forums share exceptionally detailed tips about complex virtual worlds and control methodology with accuracy and incredible end-user awareness (as effectively we have users writing for users).</p><p>What does this vibrant underground scene do for us as technical authors? Well, it should be serving to keep us on our toes and pointing towards effective uses of new platforms and media choices for our content.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-90713794296014559702013-02-12T17:09:00.000+00:002013-02-12T17:09:11.872+00:00Test yourself<p>Even the best of us make mistakes. How often have you hit ‘Send’ on an email only to wish you could stop it going as you’ve just spotted the howler in the middle of the third line? And the tweets Andrew recently scheduled in the early hours of the morning are testament to this phenomenon too. What phenomenon am I talking about? The wonderful ability of the human mind to ‘fill in the gaps’ – to read what <em>should</em> be there rather than what <em>is</em> there... at least until it’s too late to do anything about it.</p><p>We all know it’s much easier to make this sort of mistake with something you’ve written, but even when it’s someone else’s work, we see patterns that don’t exist and make huge leaps of expectation.</p><p>Sometimes, though, it’s plain old lack of knowledge that’s the problem – people are hazy on some of the ‘rules’ of grammar and punctuation.</p><p>Just for fun, Andrew and I had a go at the Guardian’s <a href="http://www.guardian.co.uk/teacher-network/teacher-blog/quiz/2013/feb/04/grammar-punctuation-quiz-test">grammar and punctuation quiz</a>.</p>I’m sure our clients will be pleased to know that we passed with flying colours.</p><p>How do you think you’ll get on? Go on, I dare you... </p><span style="color: #cc0000;">Alison</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-3966429902791231902013-01-31T09:12:00.000+00:002013-02-11T17:33:32.954+00:00Language marches onOne of my fascinations is the evolution of language and the force that we as writers can sometimes exert to change or preserve it. I feel that the study of the origins and history of the words we use are eximius (that being, something that used to have high value or standing that has fallen out of favour, practice or repute... by learning this word and definition and possibly using it yourself you’re joining my ongoing quest to get a dead word together with a revised and pertinent meaning back into the language and the OED!) and sometimes feel that as authors we have a role to play as the stewards of the language.<br />
This week I’m onsite with a client, sitting next to their existing and quite large technical authoring team. It’s fun to sit with other technical authors shooting the breeze and debating issues for the style sheet. One of the debates has got me thinking about the future of the language, and one about its past:<br />
<dl>
<dt>Articles with extensions?</dt>
<dd>When mentioning <code>.atd</code> files in a sentence, is it “<b>a</b> <code>.atd</code> file” or “<b>an</b> <code>.atd</code> file”? There didn’t seem to be a definitive source, and we found that we were divided between those who say “<i>an Ay Tee Dee file</i>” and don’t include the dot in the file extension, and those who say “<i>a <b>dot</b> Ay Tee Dee file</i>”. It might sound like a small discussion, but it’s one that would not have been necessary before the computer. Sooner or later, based on consensus, or diktat from one of the style manuals, this issue will pass into a formalised convention and technical communicators will have changed a small part of the grammar and style of English usage.
<br />
<dt>Wordy Recipes</dt>
<dd>The second discussion that came up was the consideration of the plural of “formula”. I am pleased to say that as the team was quite strongly weighted with both chemists and those with theological training, the Latin based “formulae” won out. I’m sure there are those out there who think that it doesn’t matter, or that the alternative plural endings we find on some words are tricky to teach the iTunes addled minds of the young. Yet the chemists and theologians amongst us feel compelled to go for the older ending. This was perhaps because in some ways the older variant feels like a richer source of information. Like an old bemedalled soldier on a park bench, the word seemed to lend an air of intrigue and respectability to the otherwise ordinary scene that is painted by a manual.</dd><br /></dd></dl>
Back when understanding language was more cool than eximius, an old man was receiving a literary award. He included in his speech the idea that “Broadly speaking, short words are best, and the old words, when short, are best of all.” This is good advice for a technical communicator, if acted upon it leads to writing that is accessible and understood by a wide audience. The implication however is that if we are to marshal words and have them merrily marching across landing pages, fields, sheets and books we must know something of their character. Given the influence this individual had on history, it will surprise some to know that his eventual Nobel Prize wasn’t in something mundane like peace or economics but <a href="http://www.nobelprize.org/nobel_prizes/literature/laureates/1953/">Literature</a> which goes to show that words do carry extraordinary weight. To borrow from another of his contemporaries, I feel we should tread softly, and carry a big book.<br />
<span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-22264317324970438372013-01-18T12:32:00.001+00:002013-01-18T12:32:13.937+00:00Spreading the word<p>I’ve just found myself involved in TCUK13 (the annual conference hosted by the <a href="www.istc.org.uk">ISTC</a> to which all are welcome). Kai Weber (Technical Communications <a href="http://kaiweber.wordpress.com/">blogging legend</a>) and I will be delivering the social media build up to what promises to be a signification event on the international technical communications calendar.</p><p>Now, as with any big event, some of the details are currently on a need to know basis, but it has been revealed that TCUK13 is going to be held in Bristol on the 24–26 September this year, and will feature some well-known technical communication personalities from around the world. Last year we had <a href="http://www.cowtc.com/">Leah Guren</a>, <a href="http://thecontentwrangler.com/">Scott Abel</a>, and <a href="http://www.mardahl.dk/">Karen Mardahl</a> as keynote speakers, with other presenters including Dr. Tony Self (of <a href="http://ditastyle.com/about/">DITA fame</a>) who travelled all the way from the southern hemisphere. This year is going to be even bigger, so if you’re a scientific or technical communicator, or know someone who is, you’ll want to follow the #tcuk13 twitter hashtag and <a href="https://twitter.com/TCUK_conf">@tcuk_conf</a> feed (which I'm administering this year) where all the important news and information is going to be disseminated.</p><p>The next big opportunity is the call for papers, which is where everyone gets a chance to pitch their idea for a presentation or workshop. The call will go out in the near future via the <a href="https://twitter.com/TCUK_conf">@tcuk_conf</a> twitter account and other channels. Presenting at any conference is an important career milestone, and presenting at the annual conference of a nationally recognised and internationally affiliated professional body grants you a metaphorical ostrich feather for your cap.</p><p>The really great thing about technical communicators (who include illustrators, authors, presenters, trainers and anyone else involved in the sharing and communication of scientific and technical information) is that we’re really a very supportive bunch. Even if you’ve never done anything like this before, it’s well worth getting your ideas down on paper and giving it a go as experienced presenters are available to steer you in the right direction.</p><p>Will I be presenting? Well, that’s down to the programme committee. I had half an idea for a joint session with Alison (a.k.a. mum) but I’ve been advised that <a href="http://www.youtube.com/watch?v=OFTHp4Cda7U"> juggling chainsaws</a> has already been done, so I’ll have to think of something a bit more appropriate.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-67474091498631034002013-01-14T11:03:00.000+00:002013-01-14T13:15:02.620+00:00The hidden costs of dodgy documentation<p>I’ve just finished opening a bank account for my son. This would have been done a while ago, but the bank lost the copies they’d taken of my driving licence. This means that I had to make another trip to the branch for them to re-photocopy the document (I could name and shame <a href="http://www.co-operativebank.co.uk/">the bank</a>, but in general they’re a very good provider).</p><p>What I’ve discovered is that I struggle to turn off my inner documentation beast. They sent me a sheet of A4 paper with two lists on it: one of these lists was titled “identity documents” and the other was titled “proof of address”. The instructions (personalized to me at the top of the screen) said “provide one document from list B”... as neither list was labelled A or B, I had to phone the bank to find out which of the two lists was list “B”. (This was further confounded by the fact that a driving licence is acceptable as both proof of ID and address, and yet was only in one of the lists!)</p><p>The implications of that simple mismatch between instructions and the reference table can be far reaching for a business:</p><dl><dt>Cost</dt>
<dd>The number I called was an 0800 number, so the bank was paying for my call. I spoke to the member of staff for approximately 12 minutes (as they had to “take me through security”). I’d just cost the bank wages and overheads. The individual I spoke to in the bank’s call centre said that they got calls about this “all the time”, which I suppose from their perspective is a good thing as horrid and mismatched documentation is keeping call centre staff in work.
<dt>Annoyance</dt>
<dd>How many people would decide not to pursue things any further with the bank in question? There are plenty of competitors who I wouldn’t have to phone after they’d bodged the letter that they sent through after they’d lost things.</dd>
<dt>Disbelief</dt>
<dd>An easy way to tell the difference between a phishing email and genuine communication from a bank (or any business) is the way the conman modifies the language at will, not so much to suit their own purposes, but as a clear indicator that they learnt English gathered around the village TV watching 80’s B movie re-runs. I was given the option of sending my original driving licence to the bank in the post, but there was no way I was doing anything other than taking it into the branch after they’d appeared even slightly dubious.</dd>
<dt>Bad Press</dt>
<dd>I suppose this blog is an example. Every time documents are inaccurate and it creates hassle for a customer, they’re likely to repeat the tale later in the day when blowing off steam. This could have serious repercussions for a brand, particularly if your marketplace is somewhat niche.</dd> </dl><p>So that’s the breakdown of the repercussions of bad documentation. There’s a builder in my local area who I haven’t asked to quote for me because his business card is mis-spelled, and there are call centre staff in India who I’m on first name terms with because their employer’s FAQ section consists of 2 FAQs and a smiley face (David Hamill's treatment of <a href="http://www.goodusability.co.uk/2009/05/12/faq-usability">FAQ usability</a> is well worth a read). The question to ask is how many of your customers are doing the same because of simple and easily fixable mistakes.</p><span style="color: #3d85c6;">Andrew</span><br />
Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com0tag:blogger.com,1999:blog-4230806855799860566.post-35841650697975479452013-01-07T09:00:00.000+00:002013-05-16T07:08:04.037+01:00It’s only words...<p>What is it about writing, especially factual (technical) writing, that has so many people believing they can do a better job than – or at least, as good a job as – someone with training and experience? Is it because everyone (at least, all of you reading this) can read and, by extension, write? In the sense of putting one word after another on a piece of paper or a screen, that’s true: everyone <em>can</em> write...but can they write <em>well</em>.</p>
<p>There’s something about the written word that seems to encourage people to do something they would never do with other professions. Or maybe they would. A recent experience reminded me of the <a href="http://www.bbc.co.uk/news/world-europe-19349921">attempt by an amateur to restore a Spanish fresco</a>.</p>
<p>I had been commissioned to write about a technical process in an engaging way to highlight the innovative practices a company were following. The first draft was duly submitted and reviewed by my client, quickly followed by an updated version incorporating requested changes – so far, so good. After some time chasing for feedback, I was told that my client’s customer (about whom the piece was written) had made a large number of changes.</p>
<p>I was astonished, amused and annoyed in turn: astonished that someone should take it upon themselves to make changes instead of simply asking for them to be made (especially when someone else was paying the bill); amused (and dismayed) at the stilted and disjointed result and annoyed that my client was subsequently told a ‘favour’ was owed because of the amount of ‘necessary’ work incurred.</p>
<p>I have no problem with people wanting changes to things I have written – this is normal in my world, and part of what I am (and was) paid to do. However, it would have taken seconds for my client’s customer to say, “It’s factually accurate, but I would prefer a more formal style” instead of the hours that apparently were spent ‘improving’ the vocabulary and sentence structure. The changes would have taken me much less time than they reportedly took my client’s customer – and they would have been seamless.</p>
<p>No accounting for taste!</p>
<span style="color: #cc0000;">Alison</span>Alison Peckhttp://www.blogger.com/profile/07026686189885253952noreply@blogger.com1tag:blogger.com,1999:blog-4230806855799860566.post-89158987993597917772013-01-04T15:35:00.000+00:002013-01-04T16:01:19.914+00:00New year tech<p>I’ve just read an article on <a href="http://www.guardian.co.uk/technology/2013/jan/01/technology-five-developments-rewire-world?INTCMP=SRCH">five technology developments that could rewire our world</a>. It’s quite informative, but three of the predicted developments have massive implications for technical authors:</p><dl><dt>Self-driving cars</dt>
<dd>I believe that smarter devices often make the world accessible to people without the skills they would otherwise need. Once upon a time (yes, it really does seem that long ago!) computers were only really accessible to those with the ability to code and manipulate command prompts; in the modern world even keyboard skills aren’t that essential thanks to the nature of modern tablets. The same change happening in motor vehicles means that there is going to be a sea-change in the way that we categorise drivers and mechanics. Expect drivers to have far less knowledge of vehicles in future, whilst mechanics will need to further develop into gurus of GPS and guidance systems. The documentation provided to both groups will need to change accordingly, and somewhere an entirely new vocabulary will have to be developed to describe how self-drive cars operate (possibly by tagging the word ‘manual’ onto everything we currently do: “I manual-steer my car round corners and manual-brake for traffic lights”).</dd>
<dt>Flexible screens</dt>
<dd>As technical communicators, we still haven’t quite shifted away from the flat nature of paper in books and manuals, as screens are also flat. The issues for our field in terms of accessibility and re-skilling are massive when we consider that our output may be curved around the surface of a cylinder, or even a sphere... This doesn’t make our job impossible, but it may mean fundamentally reconsidering some of the givens in the field (e.g. “in European languages, the eye tracks from top left to bottom right” because on a round surface, there suddenly isn’t a top left and bottom right).</dd>
<dt>Augmented reality</dt>
<dd>This has been around for a while in science-fiction (one of the most interesting mentions was in Michael Chrighton’s <cite>Airframe</cite>) and video games (<em>Batman: Arkham City</em> amongst others) but is yet to make it mainstream. This is about to change and I think that augmented reality is going to be one of the biggest changes to hit technical communications in the next decade. Instead of writing so that an individual user is constantly looking from product to manual and back, we’ll be writing so that the user is seeing and hearing the information overlaid on the product they’re currently looking at.</dd> </dl><p>So there we have it, not necessarily the big five, but the big three. Personally I’m quite looking forward to what the future holds.</p><span style="color: #3d85c6;">Andrew</span>Andrew Phttp://www.blogger.com/profile/00024289361254001536noreply@blogger.com1