Using Food to Improve Your Technical Writing

A Recipe For Success?

Apple Pudding Recipes by Shadowfoot on Flickr (CC BY-NC-SA 2.0)

This story is intended for anyone already working as a technical writer, or thinking about becoming one. It will help anyone wanting to improve their instructional writing by sharing a particular trick that I regularly use to hone my skills.

I have worked in the UK technology sector for 20 years; for the last 14 years, I’ve been a technical writer. I started out writing books about C++ development, moving later to online copy. My most recent work is here on Medium and over on DZone, where I’ve also recently published some tricks for technical writers.

I’m self-taught, and I cringe at some of my early work, although much of it is now unavailable because the company for which I wrote it has shut down. Phew! I’ve been lucky to work with some excellent copy editors and reviewers over the years, and I’ve also been fortunate to review and edit text written by people who haven’t been formally trained to write. Mostly, they’ve been software developers, like me, who want to simplify things for their fellow developers. I’ve learnt so much about writing along the way, and here are some of my tips.

What makes a good technical writer?

The skills needed to write for a technical audience are different to those exhibited in creative writing. As a technical writer, you need to be able to:

  • be precise and concise. We love bullet points.
  • know the audience, the problem your copy solves for them, and the clearest way to state the information.
  • write instructions as simply as you can for non-English speakers, but without omitting any essential information.
  • explain subject-specific terminology while avoiding jargon or unnecessary complexity.
  • understand what you are explaining, and appreciate the common issues in depth! You can’t choose a new technical subject and simply write about it without experience. If you’ve worked as a mobile game developer, you understand a completely different problem space to a developer working in the financial industry. Likewise for writers.

Write about what you know

This takes me to the promise I made at the start of the story — the trick to improving precision and concision if you want to try out as a technical writer. It’s simple. Write about what we all know: food.

I suggest you write a recipe a day for a week (or make it a regular practice with the 52-Week Writing Challenge). It’s surprising just how much you need to consider to keep the instructions brief, yet easy to understand. Consider the following:

  • The sequence of events. Don’t get to the end of the recipe and then ask them to pre-heat the oven.
  • Amounts of ingredients. These should be consistent (work in cups, grams or ounces, or all of them).
  • Ingredient specifics. Is the onion peeled, chopped, in rings or in slices?
  • Specific instructions, such as the oven temperature and cooking time.
  • The quantity you are making. How many will it feed?
  • The “problem you are solving”. This is probably the most important piece, and is often part of the introduction. It is where you explain what the recipe solves for the reader. For example: is this a recipe that makes a complete meal? If so, which meal? Is it a lighter dish that needs accompaniment, and if so, what would go well with it? Is it a healthy-ish cake or a luxurious treat? Will it appeal to children? Can it be made vegetarian or vegan? Does it contain allergens such as nuts or gluten? What can you do with the left-overs? The details will be specific to your recipe, but you need to be clear on them before you start writing.

One thing you don’t need for a recipe, which is something you see in a number of food blogs: the back story. This is often a delightful tale about their late-grandmother’s chair, which had cushions that smelled of mixed spice, and the cake contains the same spices, so it reminds them of their childhood holidays with said grandmother. And so on.

Enough already!

These are cute stories, great for SEO, and perfect for building a relationship with your readers when you’re lifestyle blogging. But they are not part of the instructions for making a cake, and you can omit them from your technical writing practice.

This may indeed be the best way to illustrate the difference between creative copy writing and technical writing. While tech writers describe the recipe, it’s the creative writers who win over the reader into trying it out in the first place!

Whenever I am hiring writers, I ask them to submit a recipe before I select them for interview. It doesn’t need to be for anything complex, but it is immediately clear how different people tackle it, and therefore their likely approach to technical writing. It’s also interesting to see how much effort some people put into typesetting their contribution and including photos. Sometimes I get really interesting recipes to try out too!

I hope this story has given you some insight into technical writing. Do let me know in the responses below, and please clap or share it, if you enjoyed it.

Jo Stichbury is a technical writer and developer, who freelances in the UK, and reads more recipes than she cares to admit. She can be found on Twitter and LinkedIn.

At The Writing Cooperative, our mission is to help each other write better. We’ve teamed up with ProWritingAid to do just that. Try it for free!