A foodie’s guide to working with technical writers

Claire Mahoney
Jul 10, 2017 · 5 min read

As a technical writer who watched Masterchef, I fell for the assumption that knowing more about food, made me a bit of a foodie. Enough of one to critique my lunchtime sandwich a bit more, use the word ‘courgette’ instead of ‘zucchini’, and start experimenting with jus.

How your cake will NEVER look even if you follow the recipe exactly

Then I realised what I was doing. First I thought “God, I’m a wanker”, and then I felt an echo of something familiar. People did this to me, too. They thought that having access to words meant they could use them as well as me, a tech writer of 10+ years experience. But knowing something and being able to do something are totally different things.

There are lists and lists that prove it.

So in order to avoid the wankiness trap that I fell into, here’s some advice about how to work with technical writers, without appropriating inappropriately.

Give me useful, informative feedback

WE. LOVE. FEEDBACK. Feedback is critical to tech writers. Without it, we have no idea if our message is useful, timely, clear, applicable, accurate or reliable. Feedback tells is if our message will get through.

So if you detect something not-quite-right with our copy, please don’t just rewrite it without explaining. We need lots of information to write well. We need to know how it works, who it’s for, what it does, what you want the content to achieve. Give us the ingredients and let us create! Cooking our food in our kitchen is not okay.

And the more we know, the better we write. So if you’re not very experienced at giving feedback, here’s a few tips:

  • Make all your comments about the writing, not about the writer. “I thought this sentence was a bit vague…” as opposed to “I thought what you wrote was a bit vague.” Remove all personal pronouns.
  • Focus on the outcome or audience. “I think users might find an explanation of x useful here,” instead of “you need to explain x to users.”
  • Be helpful, not critical. “I’m not sure if this is an effective approach for this situation, I wonder if x might work instead?” not “Your approach is all wrong. Do it this way…”
  • Please explain. “It’s a bit too wordy” is not helpful AT ALL. Why is it too wordy? Are we limited for space? Are the users children? Do you just not like words? Is the explanation too wordy or is the thing I’m describing too complex? Tell me everything.

Constructive, informative feedback is a valuable part of our writing process, and an essential part of review conversations. Everyone should walk away feeling positive. Imagine asking your partner what they think of your outfit, and having them throw a giant sheet over you in response.

Please don’t claim skills by association and expect cred

My mother was a nurse. But it still takes me at least three goes to put a bandaid on without it folding on itself, so I don’t think I picked up any latent nursing skills there. I left childhood with an aversion of betadine and a known bee allergy, not in-depth knowledge about wound management and antihistamines.

What I’m getting at is your partner’s job as a primary school English teacher does not give you a credibility boost. They did not pass on writing or grammar skills through skin contact. Cryptic crosswords and even heavy reading don’t really count either. Sorry. That’s because tech writing is not just good writing about a technical subject, it is a whole other set of skills entirely.

Not a real doctor

I’m not suggesting tech writing is some unassailable, ivory tower skill, but it does require a bit more than a passing acquaintance with constructing a sentence. Claiming credibility you haven’t earned (or even acknowledged exists) devalues our skills.

Would you walk up to a professional photographer and claim to be able to do their job just because you own a camera or get lots of likes on Instagram? Writing is no more stringing word together, than photography is pointing and shooting a camera. Please trust that we have gone through a lengthy and thoughtful process to compose a piece of work.

Yes, we sometimes make mistakes

All writers make mistakes, but calling it out loudly in front of others to collect some kind of grammar-kudos is monumentally uncool. Besides, there’s a difference between a typo and a spelling mistake, and split infinitives are what all the cool kids are doing these days.

But if you can’t resist the urge to call out our occasional follies, then please do it respectfully (and be correct). I’ve spell-checked every birthday card I got since I was seven, and even I know that good grammar is not as important as good manners.

Give us time to do our word thing

If you slide by a tech writer’s desk at 4pm and ask if they can have a quick look at a message that is going out to users the next day, for a feature that they’ve never seen, they’re going to be a little annoyed. It’s like expecting your partner to cook dinner for eight with one hour’s notice.

Unfortunately, there is no miracle ‘word polish’ that turns robotic-sounding tech-speak into appealing prose. Nor is there a magic bag of words in our desk drawers from which we can pluck randomly perfect descriptors. If you value what we do, give us time to do it.

Mystery bag of amazing word things that make everything sound amazing in 10 minutes or less

And when we ask what the purpose of the message is, and you respond that it needs to persuade a user to do something, but without it seeming like we are telling them to do something, that is asking a lot. It’s literally not possible to achieve both things successfully, and frankly, you deserve a salty response.

Careful what you, literally, ask me to do for you. Credit to @fjamie013 of Instagram.

How do you bake a professional cake?

Simple. Ask a professional to bake it.

  • Clearly describe what kind of cake you want.
  • Trust they know more about cake than you.
  • Respect them when they say it takes a while to cook.
  • Acknowledge that their experience of making cake will result in a better cake.
  • Stay out of the kitchen.

Otherwise, be happy with cake that looks like this.

Claire Mahoney

Written by

Word nerd and content wrangler. Making the world a simpler place, one sentence at a time.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade