: Re: 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?

@Miguel976

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)

Login to post a comment!