Technical Writer

Today I was reminded that no matter how professional you may believe you are, no matter how experienced you are, you must never, ever forget your audience.

It was the end of a project. The project files were stored in SharePoint, but in the portal server, rather than on a separate project site. (We set the project up in the early days, when we had no real idea of what we were doing.)

We planned to back down the database to store with the project, but we also decided to copy the really important document libraries down as individual files, and store them with the other project documentation. This was probably overkill, but this is an important project and a couple of extra storage discs was worth the peace of mind.

I don’t know if you have ever tried to restore SharePoint documents from the tables, but they are huge—and for some reason files of the same type in a directory restore to the same size. You can sometimes open a file, save it, and the file size reduces dramatically, so there is some sort of overhead in either the way the files are stored or in the way I download them.

However, I digress. That’s not what this blog is about.

Downloading to the network was slow. It took four to five minutes minimum to save each file. It would take forever. So I downloaded the files to my PC’s c: drive, planning to copy them across to the network later.

The download worked fine, but when I tried to copy the files across to the server I hit the same problem. Each file still took four to five minutes to copy.

So instead I decided to let people access the files from my c: drive. Our developers do it all the time, hopping on to each others machines to check out code.

I made the directory readable, and sent an email to the project managers telling them that I had put the files onto my c: drive, and gave them the name of the PC.

I forgot one thing.

These people were not developers.

They’re like most people. They expect local drives to be just that, local to the PC and inaccessible to everyone else. I gave them my PC number and expected them to know what to do.

I had forgotten my audience.

I had some other work to download for the project. Small stuff, and I had other priorities to complete first. When the project managers asked how I was going, I assumed they meant the small stuff. (Second mistake. Never assume; always make sure you are both talking about the same thing.)

It was a week before I realised what the problem was.

Two weeks out from the end of a project it was precious time to lose.

And all because I assumed my audience knew something they couldn’t possibly have known.

There is no room for ‘artistes’ in technical writing.

If you are precocious about your writing, this is the wrong job for you.

It’s a business relationship, pure and simple, and (in most cases) the client owns the work, you don’t. Your job is to give the customer (the client) what he wants.

That doesn’t mean you can’t be passionate about writing, passionate about the end result. You can, and should, but leave your ego at home.

What do I mean?

Here’s an example.

If the house style is short, partial sentence bullet points in the step-by-step instructions, don’t make yours full sentences just because you don’t like partials. Even worse, once it is pointed out to you, don’t argue about it forever more and refuse to change to suit the standard.

If you don’t like the standard, you have three options: live with it; work yourself into a position where you have some say in changing it; or get another job.

Another example.

The house style manual chooses the American-style spelling of ‘analyze’, rather than ‘analyse’. You can’t stand it. You write for an Australian audience and the word should be ‘analyse’. Whether you like it or not, that is the house style for the company you work for. It’s a common enough issue that they have specifically listed in in their style guide. You have the same three options if you don’t like it.

As I said earlier, it’s not your writing, it’s the company’s. Lovely clean, clear writing is good, but remember—you are not out to sell yourself but to sell your company, or a specific company product.

Editing is a skill I rate more necessary than writing ability for technical writers. Many people can write well. Far fewer have time or the inclination to edit what they have written, even though it’s a rare first draft that can’t be improved with a little editing.

Some people never get the knack of editing at all. Others can edit another person’s work, but not their own. A lot of people can tidy up their own text if they put the writing away for a while.

Technical writers don’t have the luxury of sitting on their work for the weeks and months it takes until they can look at it with fresh eyes. They have deadlines, products to deliver. They have to rewrite their own work as soon as they have completed it.

As most writers know, that’s quite difficult.

Likewise, most tech writers can’t rely on someone to edit their work for them. They must do the initial edits themself.

Anyone who reviews their work should not have to correct basic problems like structure, or grammar, or spelling, or format. They certainly should not be called on to make major changes to a document’s content or style.

A tech writer whose work constantly requires major editing is as bad as no writer at all.

So what skills does an editor require?

They need the basics of good writing—spelling, grammar, tense and style—but they also need to be able to look at writing they have produced and to determine things like:

• Does the writing achieves the required result?
  For example, if they are writing a procedure are the steps clear or confusing?
• Is everything covered?
• Is it aimed at the appropriate audience?
  Instructions for a novice computer user, for example, will be different to those aimed at an audience of developers.

Not only must they recognise these problems, they must also be able to fix them. And that is what makes a good editor.  The ability to look at writing you have produced, to recognise any problems, and to fix those problems.

Just finished listening to Anne Rockley’s podcast Web 2.0, CMS and DITA.

This is part of a series of podcasts called Tech Writer Voices, which has interviews, presentations, news, and tips about technical writing.

Despite the fact that we work with leading edge technology, technical writers are still basically text based (screen or print). It’s good to hear other writers talking about their work and to learn how they are using new technologies and techniques.

I highly recommend these podcasts.

Although I say writing is not the most important skill required for a technical writer, that doesn’t mean you can get away with being a bad writer, or even just a poor one.

You must be competent, and by competent I mean:

• A good grasp of the English language (or whatever language you are working in)
• The basics of grammar
• Able to spell
• Able to write clearly.

A poor grasp of language shows in what you write and how you write it. Your work has to be readable.

Likewise poor grammar shows up in bad writing. You don’t have to be a grammar grand master, but you need some basics. I don’t expect you to know what the word appositive means, for example, but I do expect you to know the difference between the following two sentences and when and why you would use each:

• Bill’s friend Alice adored the famous singer Dean Martin
• Bill’s friend, Alice, adored Dean Martin, the famous singer.

Many people can spell. Typographical errors (due to poor typing) often trip more people up than actual spelling errors. Another problem that seems to be creeping in, especially with younger people, is an inability to distinguish between homonyms. There is a lot of difference between, say, a sensor and a censor.

Poor writing, bad grammar and spelling errors not only make the finished product harder to read, they cause the reader to lose faith in what has been written. No matter how good your knowledge is, no matter how good your coverage of the material is, if the work is riddled with spelling or grammatical errors there comes a point where the reader stops trusting the document, where they say, “This person has no idea what they are talking about.”

It’s psychological, but it happens, and once you lose the reader’s trust in the material the user manual, on-line help, web page or whatever you are writing is useless.