Don't Ask
Things Not To Say to a Technical Writer and How to Respond
by Mumpy
But nobody ever reads the manuals anyway.
As said by a Product Manager in a large meeting. The correct response to this does not involve extreme injury to certain body parts. The recommended course of action is to smile brightly and announce that you’re off to the beach in that case. Other responses include engaging said Product Manager in a long and involved discourse as to the benefits of documentation in product sales etc. Note that this approach works best when used simultaneously with illegal drugs (for either or both of the parties involved).
Wow, you really take your job seriously, don’t you?
As said by a Support Engineer after I shrieked on realizing that he had inserted some bizarre English sentences into a document without telling me. My response at that time was to shriek some more, accompanied by some rapid breathing and high-pitched laughter. I’m not sure what that was about but this is not the recommended response. The correct response is to say “Yes, I do. Thank you for the compliment”.
I don’t speak Hebrew so I thought I’d go into technical writing and my friend said to talk to you about it.
As said by any number of people who have phoned me up over the past 5 years. Aaarghh. As far as I’m concerned, technical writing is not a “One Size Fits All” profession for anybody who speaks English (or Russian or French or Hebrew for that matter). I’m sure you are wondering what response I give on the phone to these people. I usually say “Oh dear, oh dear, oh dear. It doesn’t sound to me like you would be very suited at technical writing”. At which point they say thank you very much and promptly go off and become Documentation Managers – thereby proving me horribly wrong. However, the fact still remains that I think tech writing is so much more than a blanket profession for all anglos.
The English is incorrect – you are missing the word “to”.
And other editing comments sent to me by reviewers. You have no idea how many “corrections” I get to my English from non-native speakers who are reviewing the documentation. It’s sweet of them to want to try and help me – but do they honestly think they know English better than me? And the answer to that, ladies and gentlemen, is Yes. 99% of Israelis think they know English better than you. There is absolutely no correct response to this whatsoever.
Why do technical writers complain all the time?
As asked innocently by several guys in my company. Oy, oy, oy – this is a hard one. I think it just comes with the job description. After all – it is our job to accuse, ascribe, attack, fret, fuss, gainsay, grieve, gripe, wail, whimper, whine, and yammer. I’m quite proud of my ability to yammer for hours on end. In fact – I won an award once for Best Yammer of the Year – but that is a whole other story…..
For Hire Now!
Summaries
Upcoming Events
LOL! Written by a true technical writer who's been there, in the trenches. Thanks for making me smile this Sunday morning!
Very good points, Mumpy! I only have two comments:
For point one, Nobody ever reads the manuals - if you're going to suggest illegal drugs, you should provide a contact number. ;-)
For point four, The English is incorrect - on this I must disagree a little. If one of my non-native speaking developers has a problem with my English, chances are that my text isn’t clear enough. The grammar can be 100% correct, but it doesn't matter if the message isn't coming through. So, while my immediate reaction might be disdain, a moment later I'm re-examining the offending sentence, looking for ways to improve it.
Also, stupid comments about my English aren't reserved for non-native speakers alone. I've received an incredible number of shudder-worthy suggestions from our US offices, as well!
I once was talking to a developer who complained that no one read his design documents. "Tell me about it," I said. "But you don't understand," replied he. "No one's expected to read YOUR documents!"
:) The things they don't tell you in technical writing school...
To Leah - Yep - I agree with you. I also tell them that technically it's 100% correct - but seeing as how they were confused by it - I'm going to rephrase it. My article simply focused on the "moment of disdain" :-)
You say: "it is our job to accuse, ascribe, attack, fret, fuss, gainsay, grieve, gripe, wail, whimper, whine, and yammer." What about kvetch? Surely, it is also our job to kvetch.
When a native Russian- or Hebrew-speaker tries to correct your English, the correct response is to nod your head wisely and say, "Yes, but when the subjunctive form's antecedent is the predicate nominative, and the past imperfect is used..."
Hi,
So we don't know English?
This one is a classic.
Sometimes, what is written by an Israeli is technically correct English, but they are unaware of the nuances and the "slang" meaning of what they have written.
I started working at a High Tech company and had been there for only a week. I was asked to look over a "final document/pamphlet" that was to go with a piece of hardware.
It was FINAL and they only wanted me to check the spelling and the grammar.
The pamphlet was a series of diagrams with an explanation under each diagram.
(The instrument is called a XXjack tool. Can't remember the exact name and this is really testing my writing skills as I usually relate this using some very graphic gestures and this is the first time I am actually documenting the incident:-)
1. The first diagram shows the end of the instrument next to an empty jack on a network panel. The handle is held by the second and third finger of a hand, sort of cupping the instrument.
This is the instruction.
"Insert the tool fully and ensure that the tool is inserted into the space to its deepest position."
2. The next picture shows the thumb being pushed between the second and third finger. (Old fashioned "F" sign)with the comment. "Push the plunger in until you hear the click."
There were about 5 diagrams, each one progressively worse, explaining what had to be done with this tool.
I went to find a quite place where I honestly laughed till I cried. Remember I had only been there a week and I didn't want to embarrass anyone.
So I went to the person who asked me to check the pamphlet and asked him who the audience was. If it was internal (no punn intended) then I would have left it, but this was for export.
I asked if there was another word that we could use instead of "tool". He said no so I asked him to reread it carefully. He says "this is find, did you did I find any spelling mistakes". I took it to anoather three people to read, and they all said its fine, so in desperation I explained that "tool" is slang for.....
This time I did not have to laugh alone as there was this rumble through the office and a roar of laughter as everyone reread the pamphlet.
By slightly changing it and using the technical name of the instument, the problem was solved.
Hope you have enjoyed this, that I have got your imaginations working and that you too have had a great laugh.
We really need it now in the situation that our beloved Israel in in.
Heres wishing us all a laugh a day and true peace.
Sincerely Adriane Rivka Bernstein.
PS, any comments about the way my mind works, need not be recorded. I have heard them often enough:-)