Technical Writer

Pamela Kostur’s Whose Content Is It Anyway? An Argument For Modular Writing, over at the Content Wrangler site, reminded me of a common mistake beginning tech writers make.

In Whose Content Is It Anyway? An Argument For Modular Writing Pamela talks about the benefits and uses of writing modular content, and how some people are reluctant to do it. Excuses people give for refusing to use modular content range from “It’s easier to start from scratch” to “It stifles my creativity”.

Modular content is great. It saves time, allows you to work on creating new content rather than updating old, and a whole lot of other things. However, that is not what this blog is about. This blog is about a common mistake beginning writers make—rewriting content in the mistaken belief that it’s easier to always start from scratch than it is to update an existing document.

You come across a related problem with trainers, who immediately rewrite material they receive (often from technical writers) to suit their style of training.

“It’s easier to write from scratch” is the excuse many people use when what they really mean is that they refuse to change their mindset, their writing skills, to suit a style different to their own. Often when they say this they are looking at perfectly good documention, but it wasn’t written by them, and therefore they don’t intuitively follow it. That doesn’t mean it is bad (or even necessarily good), it just means that they would have written it differently.

Remember, a technical writer is a writer for hire. You are not a novelist, with total control over what you write and how you write it. You are producing content for a company that pays you to do so. Most times they don’t pay you to rewrite work they have already paid someone else to do. They want you to write new stuff, or update what is there to match changes to the product. Unless they are truly unhappy with the current wrting (in which case they probably would have hired you to rewrite it), they want you to produce material that looks and sounds like the all the other material they have.

This is a mindset you must achieve if you want to be a successful technical writer. It’s something that comes with practice.  As you gain more experience you realise what a massive waste of time and expense these rewrites are, and how unnecessary.

Does that mean there is no place in technical writing for creativity? Of course not. Beautiful, clean, effective prose is something we all strive for, but that doesn’t mean you have carte blanche to write what and how you like.

If you can see that the existing work requires editing, by all means edit as you go, but don’t change the work simply to suit your style of writing.

In an earlier blog I covered how people get jobs as technical writers, but what skillset do you require? I mean, suppose you have decided technical writing is the career for you, what skills are useful in the field?

The skills required for technical writing fall into the following main areas.

• Writing
• Editing
• Communication/people skills
• Project management
• Attention to detail
• Technical skills.

Each of these rates a blog to itself, so I’ll cover them over the next couple of weeks, but here is the surprising thing. Writing ability is not the most important of these skills. In fact, it comes quite low on the list.

Skills required vary with the role and type of work you are doing. A good division of skills (compared against writing) comes down to something like the following:

If you work in the IT industry—and possibly other industries as well—you will notice that these are fairly standard requirements for most jobs in IT, whether it be developer, analyst, tester, project manager, team leader.

So does this mean if you don’t have these skills yo should not try for a career as a technical writer?

Of course not. My own skillset would be something more along the lines of:

What it does mean is that if you are weak in a particular area—project management, for example—you should hone your skills in that area.

It also does not mean that just because I rate writing as one of the lesser skills required, you can be a bad writer and still get the job. More of that in the next post.

On a project, don’t expect that just because you you are working to the same end, you will all be thinking the same way, with the same end goals.

A recent discussion on xml schemas served to remind me of this.

We were setting up standards for the passing of data as xml between two companies.

There was some initial agreement. We would use schemas, and if the xml failed the schema validation it wouldn’t get sent. But that was about it.

One party wanted the schemas to be as loose as possible. He wanted everything typed as extra-long strings, so that it never failed validation at all. He wanted the code at the recieving end to pick up any problems.

Another party wanted dates more specific, so that dates prior to the go-live date could never be sent.

Still another party wanted the xsd to be future proof. For example, each file has its own unique ID. We set this to a maximum of six characters—but what happens when we send the millionth file? (Given that we were only sending this file once a week, I suspect the software will be well and truly obsolete by that time. Not to mention that the schema would be the least of our worries. If the length was written into the schema it would also have been written into the code as well, and that’s where our most serious problems will be—in the code.)

Then you have the technical dreamers, who get sidetracked by technicalities. The xsd date standard is YYYY-MM-DD, or you can create your own data type if you wish. Not these people. They get carried away with a technical discussion on the relative merits of why W3C chose that particular standard when, say, YYYYMMDD would have been better.

We persevered. We got a standard, and it’s been pretty robust so far, coping with all the idiosyncracies people have thrown at it. The xml that’s coming from the various supplies looks consistent, and feels consistent. That’s all you can really ask from an effective standard, I think.

I could write these blogs using native html. It wouldn’t be hard, although it would take longer, particularly to add the links once I have finished. If I was keen enough, I could even link it to a table and use calls to the database to get the information back.

I don’t.

I don’t because I use WordPress, and WordPress does it all for me.

I often wonder whether Matt Mullenweg, the founder of WordPress, had any idea of how much impact Word Press would have on the blogging community, and had he known, whether that would have made him too nervous to start.

The UK Guardian on 4 November 2006, has an article on Web 2.0, and a bit about some of the major players in Web 2.0.  Matt Mullenweg is one of them.  Jimmy Wales (Wikipedia) is another, as are the founders of Blogger, Technorati, Feedburner and so on.

These people are changing the web as we know it, allowing ordinary users to do things—such as create blogs—that were previously the domain of a technically savvy few.

Back in the days before international outsourcing, before the dot com bust, I worked as a contract writer for a government department (now sold off as a private enterprise).

We were a fairly big team, most of us long-term contractors contracting for one of the big consulting companies who ran the IT department for this particular utility.

One of the consultants was in charge of the writing team.

We used to call them ‘droids’, as in androids, because as soon as one left, another one exactly like them took their place.

You know the types—just out of university, fresh from the company indoctrination, and they’re dumped in the middle of a project and told to run it. 

These young things were bright—the cream of their university year, keen and ready to work hard.  But they had absolutely no experience running projects and every single one of them made the same basic mistakes. Every time.

We contractors could say, “But we tried that, and it didn’t work. In fact, it hasn’t worked the last five times we tried it.”

Sometimes we felt we were right in the middle of a Dilbert cartoon.

I’m sure the consulting company used the Documentation department to train their graduates. I’m sure they provided mentoring, but sometimes we wondered. Sometimes it seemed more sink or swim than any other training.

It almost seemed as if the project managers had to make these mistakes to learn from them.

Just when they were starting to get good at their job, the consulting company moved them on to a more senior position, and we ended up with another droid.