Being a Technical Writer/Editor for IT companies has made me realize this: I have a job because most engineers can't write or can't be bothered to do it properly. I guess it's the same excuse I'd use when it comes to crunching numbers: I'm generally bad at math so why bother?
Most writers aren't IT nerds. To be able to translate technical jargon into human language, we have to exert three times the effort to understand the nerdspeak first.
Here are a few things that I wish engineers I work with kept in mind so my job would be a little less brain-draining:
1. Don't be scared of articles (a, an, the).
E.g., instead of "Apply changes on configuration", say "Apply the changes on the configuration."
2. Be mindful of your verb tenses.
Here's a quick trick: consider the when of that something.
Check out this very helpful table with examples of correct verb tense usage: Verb Tense Tutorial.
3. Always start with a topic sentence.
Most of the engineers I work with immediately launch themselves into the documentation process by writing whatever they did, without considering first why they are writing it in the first place. Starting a draft with a topic sentence gives it an anchor; it helps you stay within the topic and not drift off to unrelated or, sometimes, unnecessary discussions.
When I get drafts that don't have an anchor, I end up having to backtrack, research, and sometimes have a long discussion with the engineer-author just so I could understand what s/he really wants to communicate. It is exhausting and mildly unproductive work.
4. Punctuations make a lot of difference.
Here's a fun way to check if you are using that punctuation correctly -- click here.
5. You are still human. Ease up on the nerdspeak.
Here's the reason why: No, not everyone can understand you. So, unless you're turning into a robot, please be considerate and at least provide a user-friendly definition for technical terms, especially the ones that are "proprietary" (read: no one outside of your company or your group knows what those words mean). Pretend that you're having a conversation with a live human being. Better yet, pretend that you're explaining it to your grandma.
And, as how I usually end my emails when I'm actually tearing my hair out: "Let me know how I can help" (well, now you know). Cheers!
Most writers aren't IT nerds. To be able to translate technical jargon into human language, we have to exert three times the effort to understand the nerdspeak first.
Here are a few things that I wish engineers I work with kept in mind so my job would be a little less brain-draining:
1. Don't be scared of articles (a, an, the).
E.g., instead of "Apply changes on configuration", say "Apply the changes on the configuration."
2. Be mindful of your verb tenses.
Here's a quick trick: consider the when of that something.
Check out this very helpful table with examples of correct verb tense usage: Verb Tense Tutorial.
3. Always start with a topic sentence.
Most of the engineers I work with immediately launch themselves into the documentation process by writing whatever they did, without considering first why they are writing it in the first place. Starting a draft with a topic sentence gives it an anchor; it helps you stay within the topic and not drift off to unrelated or, sometimes, unnecessary discussions.
When I get drafts that don't have an anchor, I end up having to backtrack, research, and sometimes have a long discussion with the engineer-author just so I could understand what s/he really wants to communicate. It is exhausting and mildly unproductive work.
4. Punctuations make a lot of difference.
Here's a fun way to check if you are using that punctuation correctly -- click here.
5. You are still human. Ease up on the nerdspeak.
Here's the reason why: No, not everyone can understand you. So, unless you're turning into a robot, please be considerate and at least provide a user-friendly definition for technical terms, especially the ones that are "proprietary" (read: no one outside of your company or your group knows what those words mean). Pretend that you're having a conversation with a live human being. Better yet, pretend that you're explaining it to your grandma.
And, as how I usually end my emails when I'm actually tearing my hair out: "Let me know how I can help" (well, now you know). Cheers!
posted from Bloggeroid
No comments:
Post a Comment