Guide to technical writing

Creating a winning technical trade mag article

So you want to write a technical article for a magazine, but are overwhelmed before you begin? Your mind is filling with obstacles. Surely tech-speak could bore or confuse a potential reader? How do I know what structure, style and tone the article needs? How do I work out how to keep it exciting while informative at the technical level needed?

Editorial style

Start by knowing the style and tone of your ideal publication. If you have a few in mind get a hang of the general way they’re run. What is the style, word count and structure that suits your topic? Make contact with a staff member, the editor would be ideal! Do they have a contributors’ guide, space for what you’re proposing? Have your pitch ready: that great sentence that makes your article sound worth reading.

Tone

In writing your industry topic, it’s important to consider that while the audience comprises technical peers, the tone is less formal than an in-house industry report or bulletin, while giving up nothing in terms of technical depth and insight. Think of yourself as having a conversation with a colleague, albeit a one-sided conversation. You have to use language that excites the reader.

Style & language

Articles should be short and directed — designed to put forward and follow an idea such as the solution to a design problem.

Remember, you have limited time and space to get your message across, so get right to the point. Avoid opening the article with a bunch of historical or background material. This will slow down the article, work like pouring sludge in your engine.

Structure

Consider putting background, historical or technical detail in a separate ‘break-out box’ [picture to illustrate] or boxes to accompany the main article. That way the reader can choose to read it if he or she needs it, and the information will not interfere with the flow of the article and what you really want to say. Make sure that the first three or four lead paragraphs expand on the title. Again, get to the point. Why should someone read this article? Why should they care? What are you sharing with them that they need to know? Be technical. You need technical detail to be believed.

Articles shouldn’t have a formally labelled introduction or conclusion/summary. Instead, articles should be fast-paced, to-the-point technical articles.

Don’t go to a lot of trouble doing fancy paragraph formatting or doing a lot of creative layout work in your Word document. Whatever you do cannot and will not be reproduced in the magazine. Editors turn in plain copy (which may have a few subheads, bulleted lists, etc.) to the production department.

Headlines

Try and use a good and punchy headline, preferably with a verb in it. See which of these two is more likely to grab your interest: “New Generation Technology Takes the Pain out of Audits” or “Drones Revolutionise Compliance Audits”.

Abstract

Articles are often published with a short summary under the header, after the by-line or writer’s name. This consists of one or two sentences in a type larger than the article body, but smaller than the headline that gives the reader a little more information about the subject matter. It is a summary presented before the article that offers an overview and main points. If you don’t supply one, the editor will. So best to write it yourself and get it right!

On bullet points: the good, the bad the ugly

Be careful about how you present technical detail. Some stylistic pitfalls to avoid are the over-use of subheads and long bulleted lists. Subheads should be used sparingly to set off the major parts of an article. Using a subhead before every paragraph causes the reader to hesitate and actually interferes with the flow of what you are trying to communicate.

Bulleted lists can work in some contexts, and in others seem like sheer laziness. They run the risk of killing a conversational tone you have developed. Bullet items can be used sparingly as long as they are

  • Short
  • Fit tightly together in the same topic, and
  • Will be explained in more detail in the article.

Some things to avoid

If you’re writing a marketing piece, don’t let it sound like your average one! That is, don’t announce how great something is without substantiating your claim. This raises the need to include technical detail to back your points.

Language

Write tightly. Don’t run on with lots of long, adjective-heavy sentences. Also, try to use the active voice. When you are finished, do a search for the words “is” and “will” and “are”. Try to remove them by substituting more active verbs. Example: “The MP configuration is very large, made up of up to 128 CPUs.” Instead, try: “Up to 128 CPUs make up the MP array. These CPUs connect…”

Also, watch out for “of” following verbs which typically indicates a passive voice. Example: “The use of drones simplifies audits.” Instead: “Drones simplify audits.” Sentences in active voice have a directness and keep the reader interested.

Expand all acronyms on first use, except acronyms that every reader is expected to know. Try and avoid jargon. Write your article so that anyone can understand the basic precepts behind it.

Write about what you can prove. This is not the place for opinions or editorial license.

Remember you’re not writing a sales brochure. Although there is a marketing goal behind getting the article published, don’t write it as such. You want to build an opinion in your readers mind that you are credible and worthy of consideration in your area of expertise.

Write about the problem in general, and about your solution in particular. When finished, read the text out loud to yourself. Flaws will emerge and this will help you fix them. Ask yourself if this is how you would explain the topic to a colleague if he or she were in the room.

Put your name and company as the author. At the end of the article put your company, where it is (city and state), its contact phone number and web site address. Also put the name, phone number and e-mail address of your marketing communications or PR person for our Managing Editor to coordinate with.

Images

Make sure that all illustrations have a caption. Each caption should be at least 2 lines long and explain the illustration with reference to the article. The caption should bring a little more information — based on the illustration — than is contained in the article. In other words, it should not simply contain text copied from the article. Be clear and legible.

For photographs, such as screenshots or pictures of boards or other hardware, print publications tend to require a resolution of at least 300px. The preferred file type is JPEG, although BMP, GIF or TIF can also be used. It is not necessary to send 6MB TIF files when a 1MB or so JPEG file will do.

So you’ve read the guide and it feels clear as mud? Why not get a hand? You can write and we can edit, or you can talk and we can write! Book a chat with us to discuss renting a copywriter.

Share the Post:

Related Posts

Wingz-butterfly

How can I help you get your Wingz to fly?

Book a free 30-minute discovery session to see if I’m a good fit and how I can help you.