ITauthor

There's a Russian saying I once heard at a funeral. It goes like this:

A loved child has many names.

I'd like to think that maybe the multiplicity of titles given to people who do the same or similar role as me suggests that we are a well beloved function within our organisations. However, experience tends to suggest otherwise. More likely is that the many names signify an identity crisis in the profession, or an attempt at aggrandisement or a search for job security - or a mixture of these and other factors.

Whatever the reason, I thought I'd list some of the names I've come across for jobs that, behind the title, can sometimes be very similar:

• communications officer
• content curator
• documentation developer
• e-learning author
• information architect
• information designer
• information engineer
• knowledge engineer
• technical author (inf. tech author or TA)
• technical communicator
• technical writer (inf: tech writer)
• user assistance developer

Have you come across any others?

Our Sales Director phoned me up today and asked for help with some bid work that's coming up. I've already rearranged my plans for next week to help someone else with some other bid work, so I apologised and said no. As I was turning him down I was already feeling bad about it because I've made a point of telling people that tech writers should be involved in bid writing.

Then this evening I read this blog post by Mark Metcalfe: Tech Writers Need to Learn to Say Yes

Maybe if I'd read this I would have set out the options, rather than saying no. However, I worry that it's not quite as easy as Mark suggests. Very often requests for time come out of the blue and the start date is today. If you give a qualified yes, the person may hear what they want to hear - the yes - and conveniently forget the discussion of workload, cost and priorities. Often you are responsible to deliver work for several people at a similar managerial level and each of them thinks their work is the priority. Escalating to a more senior managerial level can be problematic because escalation generally has to happen through one of the managers concerned, who have little incentive to trouble their boss for arbitration.

So maybe, as well as learning to say yes more often, the tech writer needs to learn diplomacy and negotiation skills. Give a tentative yes to everybody and then get them to sort it out between them. Get everybody in a room if possible. Who's going to give way, because there's only so much you can do? So doing C means rescheduling A and B.

But if doing C is the best thing for the company then it would be crazy not to do it just because you'd already planned to work full-time on A and B.

In a recent post on the Cherryleaf Technical Authors Blog, Ellis Pratt describes four levels of support that users turn to when they need help using a piece of software.

I'm not sure I agree with the order Ellis places these in, so this is my reordering (and rewording) of the four levels:

• Ask a friend - usually by instant messaging, maybe by text or email, increasingly via twitter
• Ask the local expert - Ellis calls this the 50-foot guru: "the person within 50 foot of your desk who is more knowledgeable than you"
• Search for help yourself - most of the time this means Googling for it. You might use another search engine, but Google remains the default means of finding information for most computer users
• Call support - this might mean phoning your internal IT helpdesk at work, or it might mean emailing the company that produces the software with a support question and then waiting for a reply

I haven't numbered this list because the order is debatable. Some people don't like admitting they don't know stuff, so they'll always search for themselves before asking someone else. Other people have the attitude: I've got a helpdesk and I'm gonna use it - and they'll pick up the phone to support whenever they get stuck. On the other hand, I suspect people increasingly aren't prepared to wait for a reply to a support call - they've got to have the answer right now, which is usually when a local expert is required. And then for some any excuse is a good excuse to text, tweet or instant message their friends.

These four levels relate particularly to younger users - Ellis says "primarily those under 27", I'm not sure why 27 specifically, but I know what he means. Google first emerged into the public consciousness in 1998, when today's 27 year olds were 15. By that time ICQ and AIM were well established instant messaging platforms. So people around that age and younger have lived their entire adult lives in the Google world, and often they've been using instant messaging as an everyday way of chatting to friends since they were in school. I definitely think people in their late twenties and below are less prepared to invest time digging around researching a subject to find answers than people over 40 (like me).

But even I sometimes don't bother looking up the documentation provided by the software company. In particular, these days I never bother looking up the help systems in Microsoft Office products. Experience has time and time again proved to me that it's simply a waste of time. There's obviously lots of information available from Microsoft - usually when you search the Word or Excel help you get lots of results - but you just spend far too long doing all the leg work, looking through page after page, and often don't find what you're looking for. Go to Google and search from there and you'll usually find the information you need among the hits on the first page of results.

But going back to the four levels of support identified by Ellis Pratt. What about the manual, he asks, where does that fit in? Well, in many cases, that's now one of those things users find by Googling:

many may not recognise it as a manual. It might not have an index, page numbers or a table of contents, but it serves the same function.

The traditional manual is, in most cases, an anachronism now. And traditional ways of creating documentation, based on the way we used to produce printed manuals, are equally anachronistic, even if they're now applied to creating online help. And hey, if most people get their answers about using an application by asking their friends or the local expert, do we even need documentation at all?

Well the answer is yes. Information still needs to be packaged and presented. It's just that this can be done in a different way now, and the information very often gets to the end consumer second or third hand. For a variety of psychological and sociological reasons there are still people who are prepared to invest time learning all about an application. This person becomes the guru. The guru gains some sort of reward from this role and he/she passes on the information to others, who can then share the information with their friends. These second-hand recipients of knowledge are not gurus but they can still, from time to time, supply answers to IMs or tweets asking for help.

Apart from the gurus, the other group that still regularly finds documentation useful is support staff. They'll search a help system on behalf of users who can't be bothered to do so for themselves. And the support staff may even be involved in writing the documentation (this is the ScreenSteps philosophy). Either way, the documentation is the knowledgebase or knowledge repository in which answers to users' questions are to be found, and the support staff can answer a support call with a link to a page in the documentation - typically a specific help topic.

As technical writers we should have no fear that there will be no work for us to do in a few years. Software is going to be around for some time to come and all but the simplest software applications need some sort of user assistance. But it might be that we're not working in a role called "technical writer" - and we almost certainly won't be writing traditional manuals with a title page, table of contents, chapters, appendixes and an index.

But then - despite what many people imagine - I believe most user assistance professionals aren't spending much of their time writing that sort of traditional manual right now anyway.

I haven’t got round to doing a podcast for a while. I’ve been using up the remainder of my holidays recently, having lots of long weekends, which should have given me plenty of time to do one, but instead I’ve been doing … well, hang on a minute, what have I been doing?

I’ve been interviewing technical writers recently and it’s set me to wondering about the fundamental requirements for a tech writer. Here’s what I’ve come up with.

This is my list of skills, abilities and personality traits that no self-respecting tech writer should be without:

1. Communication skills

So much of the job is about communicating in one way or another – not just writing. Before you ever put metaphorical pen to metaphorical paper you’ve first got to be able to talk to people. You’ve got to be able to understand what people mean – which is not the same as understanding what they’re saying – and then you’ve got to be able to process information, digest it, store it up, remould it, present it, verify it and rework it.

2. Writing skills

You must be able to deliver a high standard of written English. This doesn’t mean you have a vocabulary to rival Anthony Burgess’s or you’ve memorised Fowler’s Modern English Usage. The tech writer's job is to take complicated things and make them easier to understand. Sometimes you’ll do this using diagrams and videos, but mainly you do this in writing. So the key skill here is being able to write in such a way that people can read what you’ve written, just once, and understand what you’re saying.

In technical writing we have little use for nuance and colour, light and shade, or even humour. It’s no good if what you’re trying to explain is open to interpretation, especially if it’s open to misinterpretation! Clarity and simplicity are everything.

Novice tech writers will often try to write in a way that sounds technical. Maybe they’re intimidated by being surrounded by developer gurus speaking a language they find difficult to understand. And they compensate by using technical words and long sentences. So  they’ll say “utilise” when they mean “use”. But the best technical writers are the ones who cut through the jargon, pare down the language and make complex procedures easy to comprehend by breaking them down into easy-to-digest chunks, framed in simple, well-formed English.

The motto of the help author is: "Make the reader feel smart." You want the reader to pull up a help page, find what they need to know,
read it quickly and understand it completely, and go away and do what they need to do, successfully. You want to send them away feeling good about themselves.

One of the keys to being able to do this is knowing your audience. Hopefully, you have a good idea of who your audience are. But most likely you’ll have several audiences. So, another of the writing skills you need is the ability to write at the appropriate level for an identified audience.

3. Attention to detail

It’s those little things that make all the difference. If you’re writing technical manuals for Boeing, or pharmaceutical guides for Pfizer, you will get the detail right because people’s lives depend on it. But even in other sectors, you can’t afford to make little mistakes. One small mistake in a help system and the person who went there looking for help will lose confidence and will probably decide that next time they have a problem there’s no point looking for assistance from the help system.

And it’s often those little things that people often only pick up sub-consciously that make them decide whether something is professional and dependable, or amateurish, and therefore unlikely to be reliable.

4. Interviewing skills

This is very much tied in with Communication Skills but I wanted to pull it out separately because I think it’s very important. By and large when you’re documenting software, you’re assigned to work on something that’s already in production. Other people know about this thing, and you need to find out all about it and quickly. So it’s very important that:

1. you can talk to people
2. that you can identify who you need to talk to
3. you can ask the right questions

You also must be able to listen. The art of the interviewer isn’t just in his clever questions, it’s in his ability to let the other person answer the question.

And you mustn’t waste people’s time. This is a law of software development: there is never enough time. Of all the subject matter experts you need to talk to, developers especially always need to get back to doing their job and you need time to write the documentation. So you can’t afford to waste your time – or theirs – by asking unnecessary questions. Avoid turning the discussion into a general chat, because next time you ask to speak to them they’ll assume it’s going to take a whole chunk out of their morning and you might find they are less willing to talk to you.

In a software company subject matter experts come in all sorts of guises. They’re often the developers, but they can also be product managers, QA engineers, support engineers, maybe (if you're lucky) they might be tame customers, or they might sometimes be your fellow technical writers. You need to be able to identify who the real subject matter expert is, and not just interview the person nearest you, or the person who talks the most.

5. The ability to grasp new information quickly

In my experience developers or subject matter experts are happy to tell you the stuff you need to know, provided you approach them in the right way and you don’t constantly bug them. However, they have no time for people who ask them the same question more than once. If they explain something to you once, they shouldn’t have to go over it again a couple of weeks down the line.

You need to be able to get to grips with how things work, assimilate new information and be able to extrapolate from what you know to make educated guesses which you can then verify with the experts. Good tech writers pretty much always like new stuff.

Part of the fun of being a tech writer is getting to work on new stuff, finding out how it works, and getting to explain it to other people. So the next must-have for a tech writer working in the software business is: 

6. An interest in (and preferably a fascination with) technology in general and software in particular

You have to be technical to a degree, although you don't need to be an expert. It helps to have an understanding of the technology you'll be working with, but it's also good not to have spent too much time in the minute detail of it, because it also really helps if you can think like someone who's never seen the system before. That way you can identify which bits of the system are likely to be difficult for non-technical people to understand. When I'm recruiting tech authors I always look for people who like to find out how things work.

7. The ability to structure information logically

Technical writers often deal with huge amounts of information. Manuals may have hundreds of pages, help systems may have thousands of topics. So you need to be able to analyse, plan and structure your documentation.

You’re going to have to think about how the information you’re supplying will be used, both by the reader (who may be reading this paragraph in isolation from anything else – or they may come to it after reading a couple of hundred pages before it) and in terms of how that information is used by you and your fellow tech writers (for instance, being shared between documents). You possibly also have to consider how the content you supply will be used by other departments within your company.

One of the key concepts in documentation over the past 10 or 15 years has been the idea of single source: writing something once, in one place, and then reusing it in different contexts, in different publications and in different media. For example, you might write a little section of text that will appear in several manuals, several help systems and on your company’s corporate Web site.

8. Patience in problem-solving/troubleshooting

Technical writers are usually working with things that are still in the process of being built. So, often, these things don't work properly, or they get changed without much, or any, warning. Sometimes technical writers get upset when this happens. They get stressed out because the fact that stuff doesn't work makes it hard for them to do their job. And sometimes they might get grumpy and narky because nothing ever seems to go smoothly.

These guys may be good technical writers, but they tend not to love their jobs.

So, if you’re not a technical writer right now but you’re reading this because you’re thinking it might be a job you’d like to have, think about how you’d react to working with immature, first-pass, partially built software. If you think it would annoy you being asked to document something and having to go through repeated attempts at installing, tweaking, uninstalling, reinstalling, reconfiguring, finding the right people to ask for help, figuring out the right questions to ask, try-try-trying again (Robert Bruce style) before you can even start to figure out what you need to document … If that's likely to annoy the hell out of you, then technical writing really isn't for you, because, in my experience, as a tech writer if something you’re working on is broken you usually can't just get someone to fix it for you. Generally you’re going to have to fix it yourself.  So you should have the ability and willingness to install and reinstall software, sometimes time and time again, without picking up the PC and throwing it at the wall when, at the fourth or fifth time of trying, the software still doesn’t work.

Basically, you need to do what you’re documenting. This means that if you’re writing instructions for how to install some software, you need to install the software several times, as you write,  and then when you think you’re finished you have to need (for your own peace of mind) to go through it all again (with your user’s hat on) and install it again, hopefully one last time,  doing only what it says in your instructions, and check that it’s easy to follow – and it works.

9. Graphic design skills

The first documentation manager I ever worked for had this habit of drawing diagrams. Whenever I went to ask him to explain something, he would, as likely as not, reach for pen and paper and start drawing me a diagram. At first this seemed really odd behaviour to me. Documentation was all about words, wasn’t it? Someone who had been a technical writer for years should surely be well able to explain things in words.

But after a while I realised how effective it was as a way of explaining things. And, more than that, I started to suspect my brain worked better in pictures than in words because I found that the habit was rubbing off on me. I realised that whenever I was struggling to get to grips with a concept – or just to piece things together in my head and make connections, and make sense of something – invariably I would feel the urge to sketch the thing out as a diagram.

Technical communicators are increasingly required to produce diagrams, annotated screenshots, videos with accompanying narration or even cartoons and animation. And if you don’t believe me about the cartoons, go and take a look at the work of commoncraft.com. Now, you definitely don’t need to be a designer to be a technical communicator. But I certainly think that you’ll be a better technical communicator if you have some sense of design and a facility with images and diagrams.

10. The ability to review other writers’ work

Technical writers often have to work alone. There are a lot of little software companies out there for whom hiring a full-time tech author is one of the first signs that they are taking the business seriously and thinking about user experience and they’re more than just a band of coders and a sales guy. However, tech writers perform better when two or more of them are working alongside each other, or at least: they’re working in the same organisation. Personally I hate sending my work out into the big wide world without it being checked by a fellow technical writer.

Product managers and project managers,  who review your work, will tell you if you’ve targeted your documentation incorrectly, or if you’re making false assumptions about the end users, and developers will pick up on details if you’re claiming the software does something it doesn’t. But there’s a level of editorial review that a fellow tech writer can give you, that no one else can. Because sometimes you just can’t see an obvious mistake for looking at it, and that’s where a peer review process can save you from looking like an idiot for letting something daft slip through to the customer.

So those are my ten must-haves for tech writers. Do you agree? What would you add to the list? Drop me a comment.

Note: This is an adapted extract from a talk on technical writing that I recorded earlier this month for The Writing Show podcast.