• Home
• Services
• Writing
• About
• References

Are You a Good Technical Writer?

Most technical writers I've met are definitely more writers than they are technical, and frankly, it annoys me.

I believe that techwriters should have a genuine interest in technology, while in fact, many take pride in "staying clear of all the technical details". Just like a former colleague of mine who once said:

If I'd had the authority to do so, I would have sacked him on the spot for even saying that - what did he think he got paid to do? Correcting misspellings and moving around commas? We could have hired a student or a retired school teacher to do that. Instead I would have expected something like this from a professional techwriter:

That way he would come across as more than just a helpless spell checker.

Looking at other businesses, no newspaper will hire a sports writer who doesn't know the rules of football, and certainly no pharmaceutical company would ever consider hiring a medical writer that has no knowledge of medicine. So why should technical writers be allowed to be technically ignorant?

Fed up with this ignorance and with a bruised professionalism I've decided to publish my take on what level of technical insight you should expect from a technical writer in the software industry today. Hopefully this can help set the standard.

• Computer User Skills
• Programming Skills
• Network Skills
• Hardware Skills
• Conclusion

Computer User Skills

As a technical writer in the software industry, you must be able to use a personal computer with the skills of a "super user". If you can't comfortably work with any desktop application, there's no way you can possibly write good instructions for others on how to do so. You should be able to use Windows, Macintosh and Unix/Linux systems alike.

Bearing this in mind, I'm almost embarrassed that a Web site for technical writers in Denmark has a guide on how to create rules in Microsoft Outlook. I'm sure the guide was written with the best intentions in mind, but it should be superfluous to the techwriter audience at the site.

On the same note, I once caught a former colleague replacing all occurrences of umount with unmount in a Unix manual. "The foolish engineer has misspelled it throughout", he laughed, as he hit "Replace All".

I pointed out that the Unix command for unmounting a device is in fact umount, and at that same occasion the idea of writing this article popped up the first time.

Programming Skills

If you're writing documentation for developers, you should be able to write small computer programs yourself and have an understanding for both procedural and object oriented code.

You should be able to answer questions like what is a variable? A loop? A conditional? A switch? A function? A class? A method? What's a parameter? A return value? What the difference between pass by reference and pass by value? What is polymorphy and inheritance all about? What's the difference between overloading and overriding? What's the difference between a compiled language and a scripting language?

A good knowledge of relational databases wouldn't be out of the way either, and you should know basic SQL syntax and be familiar with concepts like joins, views and stored procedures.

Good developer documentation written with insight can save a ton of frustration, time, and in the end, cool cash:

• New developers on your team, or developers from other departments, will find answers to their questions in the documentation instead of wasting core developers' time with one-on-ones.
• You'll get way fewer support calls and emails from customers using your software.

You'll get recognition all around if you can help achieve this.

If you're writing end user documentation and online help systems for desktop applications, you don't necessarily need significant programming skills. However, you should have an understanding of GUI programming in order to understand how the user interface works.

If you know what is possible, the developers won't get away with an: "I'm sorry but we just can't do that". Also, often a techwriter is the first user of an application, and if you have a bit of technical insight you can help shape the product during development.

Network Skills

Knowledge of network technologies is another cornerstone for techwriters in the software industry, so don't be scared when asked about subnet masks, NAT or the structure of IPv6 packets.

This kind of knowledge is useful when documenting software that communicates with other systems over a network, and perhaps even more important when doing installation guides for larger systems.

You shouldn't be able to layout huge network topologies, but you should have a fair amount of knowledge about IP network technology. Know how gateways and firewalls work. Know what ports common services answer at - why can you retrieve both email and Web pages from the same URL? Know how to connect to other computers using ftp, telnet, ssh or remote desktop, and be able to explain how DHCP works.

Hardware Skills

Though you shouldn't be able to assemble your own computer from spare parts (though it wouldn't hurt), you should know of the various components that make up a computer and which role they play.

You shouldn't be thrown off by questions like:

• What does it mean that your computer swaps memory on disk?
• When talking about hard drives, what's rpm short for?
• What's the difference between RAM and ROM?

Hardware knowledge is just as essential as the general computer user skills mentioned earlier. It's like knowing the basics of your car - it feels good to be able to at least change the oil and maybe a filter every now and then.

In addition, hardware knowledge is obviously useful when writing hardware requirements.

Conclusion

So, am I asking that all technical writers really be engineers? No, certainly not - there's an ever increasing demand for people with dedicated communication backgrounds to aid software to success.

I'm simply asking that the average technical writer shows genuine interest in the technology he's trying to communicate - how else can he possibly justify his presence in the software industry?