: What are the key skills for a new technical writer? For those that are just starting out, what are key skills they should have or learn to be a good technical writer?

Vote Up Vote Down

Assuming you write other things (id est, assuming you have ease of written expression), there are four skills to polish that apply to all of technical writing.

Simplicity through division: Break complex ideas in many simple ones.
Simplicity through vocabulary: Use everyday words whenever possible without sacrificing precision.
Simplicity through organization: Set the text up in a way that every concept is readily supported by previously explored concepts.
Simplicity through tidiness: develop an unobtrusive way of explaining terms. Sometimes a footer is a distraction, sometimes it is the most appropriate.

Through practice and observance of those principles, technical material can become enjoyable reading material.

After you develop those skills, there are some steps (not skills) you need to follow in order to be a good technical writer. Others that answered before me mentioned some of them (such as knowing your audience), but as I think that's not the spirit of the question I'll not address them. They are, of course, key for successfully writing technical articles, so you should heed those answers too.

(0)

Vote Up Vote Down

Knowing who your audience is makes for a good first step. Writing end user documentation isn't the same as documenting an API, and shouldn't be approached the same way. Your audience defines everything that comes after, and how simply you need to present concepts.

As Lauren noted, writing simply and plainly is solid advice, no matter who you audience is. Simplicity is determined by your audience, but the "plainly" side isn't. Along similar lines, pictures, diagrams, and screenshots are wonderful. Never say with words what you can illustrate with a screenshot. Remove any cruft from a screenshot that's tangential, or could distract from the message. I think this is a decent example from my own personal stuff that demonstrates an appropriate mix of illustration with text, and snipping out cruft.

Most of the work I do is end-user documentation. As such, I try to keep my mom in mind when I'm writing it. She's smart, but not technically inclined. Could she understand the concepts and do what I'm explaining?

Some things to avoid:

I've noticed a lot of software developers use words like "trivially", "obvious", and other off-putting vocabulary when they're writing technical content. This is bad. You're not doing math proofs; there is no QED in technical communication. No one cares how smart you are, or how easy it was for you to figure out the solution. I've gotten to the point where I just close the browser tab if I see too much of this.

Perfectionism is another pitfall. Technical writing needs to be good enough. It doesn't need to be perfect. You're not trying to be James Joyce. Technical communication is about accomplishing a task, not winning the Pulitzer. (Not that you shouldn't actively try to get better at your craft!)

Don't include too much detail, unless you should. This goes back to your audience again, but your job as a technical writer is not to impress the engineers who built the system with how clever you are. I was writing some documentation for an iOS client a few months ago, and I started explaining how the back end works in the quick start guide. The developer mentioned that the first draft was a little more complicated than he was looking for, and he was right. End users didn't care how the client chose a connection mode; they just wanted it to work. Save that stuff for the in-depth documentation that'll be put in a KB, not a quick-start guide. Similarly, what you find interesting about what you're documenting is not necessarily what the audience will find useful. Scope creep isn't just limited to engineering projects.

Avoid devices that distract from your message. If you're telling someone how to set the clock on their VCR (heh), you don't need to tell it in story form. I feel ridiculous for even mentioning this, but I've seen it done(!).

(0)

Vote Up Vote Down

Be clear. Write simply and plainly. Define your jargon and your acronyms, even if you think everyone knows them already, and use jargon as sparingly as you can.

Imagine handing your document to someone outside your field (or better yet, try to get an editor outside your field) and aim for your work to make some kind of sense to that person. Obviously an extremely sophisticated technical paper isn't going to make complete sense to a lay person, but that person should at least be able to get the gist of what you're saying.

(0)