All you need to know Technical Writing?

Being experts in a certain subject does not mean being able to know how to spread it as well. Communication is a discipline in itself, and experts have to take into account many aspects that lie outside their job. This is why drafting a technical text can be more difficult than expected. This article explains how to approach technical writing and how to solve the typical problems that it entails. In this article, we will explain everything you need to know about technical writing.

What is technical writing?

There is no precise definition of a technical article: all articles that deal with a particular scientific aspect (a mathematical theory, discovery of physics, research in the medical field) can be considered as technical (creation of electronic circuits, use of Office, color theory, and photo editing). Usually, the goal is to inform the reader and help him solve a certain problem.

When we talk about technical writing (the technical aspect is often preferred, and for this reason, it is also known as technical writing), we usually think of the world of engineering and science. In reality, today, one encounters technical texts concerning practically every activity and profession. Think of an article on human metabolism, which can be read not only by doctors but also by athletes and personal trainers or to the technical brochure for the boiler or the package leaflet of a medicine. The handouts on Excel distributed in many companies to secretaries can also fall into this category.

In industry, professions, state bodies, research institutions, schools, technical articles (in the form of documents, reports, articles, white papers) are important to inform and guide in carrying out activities. Even the individual citizen, who, as a hobby or out of necessity, wants to specialize on a certain topic, often finds them indispensable (think of the computer or electronics magazines sold on newsstands).

The spread of the internet has greatly expanded the field of technical writing, also because today's paper is no longer the only means of disclosure, and many articles are published only on the web. Anyone can open a website on a certain topic, and be visible to the whole world at virtually no cost. On the web now, you can find sites with technical articles on any topic, some well done, some not. The discipline of technical writing requires both technical (for the contents) and humanistic (for the form) skills. Many authors are very experienced in a given topic but are unable to explain it effectively to the general public, often simply because they are not used to writing articles.

This is why in some large organizations (especially North American), the technical documentation is drawn up by special professionals who collaborate with technicians (which can be computer scientists, engineers, doctors, physicists): technical writers.

But if you follow a few simple rules, it is not difficult to write a good technical text. Precisely for this reason, we have collected some tips to solve the most common problems that a technical writer encounters in writing an article, both on paper and on the web. 

Theme and structure of the article

Prefer topics in which you are expert

Whittington's "first law of communication" (counted among the famous Murphy's laws) states that "when someone explains a subject that he or she does not understand, it will only be understood by those who know more than him."

Having a deep knowledge of a topic helps to avoid making mistakes, which would compromise the image of the author and publisher? It helps to choose the most interesting aspects to deal with because they are automatically suggested by personal experience and by errors matured over time. Finally, it helps to write better, to choose the right words, the most effective examples, and the clearest logical thread.

Define your goal

An article must have a goal: to demonstrate, resolve, clarify, explain, and frame.

Always keep your goal in mind when writing, and if it is not clear from the title, specify it in the introduction. If the path to be taken is complicated and requires many "stages," anticipate it to the reader and at each step recap what you have done and what you are about to do to reach the "goal." The reader must understand at all times where he started from, where he will arrive and where he is.

Write an effective title, buttonhole, and abstract.

One of the most common difficulties among novice authors is giving the article a clear and effective structure. Broadly speaking, all technical articles consist of an introduction, a body (divided into several paragraphs), and a conclusion. However, many fail to make the most of this division and distribute content in a balanced way.

The introduction serves to "appeal" the reader and to promise that the trust placed will be repaid in the rest of the article.

If you don't know how to get started, try asking yourself, "What is the problem this article solves? What will the reader have learned at the end of the article?" and use the answers to model an effective introduction. The introduction does not necessarily have to be written first. Indeed, it is often written when the work is finished, when you have clearer ideas about how the contents are articulated.

The same principles apply to the buttonhole or abstract when they are provided for in the article or document. The bottom line is mainly used to attract the attention of the reader (in two or three lines) and convince him to "immerse himself" in reading.

The abstract is the simple summary of the article: it concentrates its content and conclusions.

Furthermore, introduction, buttonhole, and abstract are the elements immediately visible in the browser: hence their important persuasive function.

Let's see an example in a topic sounds and animation:

Summary

The Windows MCI allows you to play sounds and animations within your application. The article shows how to take advantage of these API functions by creating a convenient interface class.

Title

Sounds and animations 

Abstract VB applications

It often happens that you have to play in your application a sound or an animation associated with an event (such as pressing a button) or during the execution of a routine (such as copying a file). In Visual Basic, there are various controls, also provided by third parties and freeware, that perform this function, but sometimes it can be excessive to include an OCX in the project. We can, with the same amount of code necessary to manage the control, act on the Windows Multimedia Control Interface (MCI). In the long run, however, it can be repetitive and tedious to deal with the various phases such as initialization, execution, error handling, and so on. In this article, we will explain how to create a VB class that manages the playback of multimedia files avi. , wav. and mid. greatly simplifying the programmer's life and relieving the program from unnecessary OCXs.

The article was published in a computer programming magazine, so the type of reader was well defined. You have surely noticed how vocabulary is very sectorial. Since the article is of medium level, the concepts of MCI, Windows, application, API, classes are already taken for granted in the article body. In this case, the title already makes it clear what the article is about. Note the adjective "comfortable," which emphasizes the benefit of reading. Finally, the introduction explains the problem and anticipates the solution and advantages (note the verbs "simplify" and "lighten").

Use a top-down approach

The body of the text must be divided into paragraphs.

A standard form of organization, useful for beginners and always effective in technical articles, is the top-down one, i.e. "from general to particular."

Start by explaining the general lines of your topic in one paragraph; in the following ones, you will deepen the sub-sections of the topic, one by paragraph.

In the end, a practical example should not be missing (in an article that explains the theory of colors and how to improve the tones of a photo, the reader expects a practical example of intervention on real photos).

The top-down method guarantees excellent results with novice readers (who are gradually introduced in detail) and is always appreciated by experienced readers, who can review a topic on occasion and can easily jump from the general part to the details.

In conclusion, summarize what has been explained in the article and what the reader is now able to do: create an integrated circuit, create an Excel spreadsheet, establish a personalized diet, correct the defects of a photo, and solve a certain mathematical problem.

The conclusion must take up what you set out to achieve in the introduction, showing that you have succeeded. Remember that for completeness, you must also mention the negative sides, if any: this will not diminish the value of the article at all. On the contrary, it will prove your in-depth knowledge of the topics.

The contents

The content should be Comprehensive, but not too much. Determine from the beginning the type of reader you are targeting (beginner, medium, expert). If it is not clear from the context (many sites indicate this in a box), specify it in the introduction, along with the preparation the reader must have to understand the contents.

Throughout the article, keep the typical reader in mind, trying to explain concepts you think they don't know. If you are on the web, it may be useful to provide links to other articles or sites. Try to give the reader all the information they need, but not all that you know about a certain subject.

If the article is aimed at an already experienced audience, you can skip some basic explanations, but be sure to cite some literature references (or links) on the topics you are skipping, so that even beginners have the opportunity to prepare before reading. 

Facts, Not Words

Never divert attention from the reader's point of view. At the end of each paragraph, the reader will ask himself, "What is it for in practice? What are the benefits? What does it involve? ". A well-written article must promptly answer these questions, even anticipating the answers to the reader's questions and doubts.

It is interesting to know that "Google offers a Web service to interface with its search engine.”But it will be even more so (and also for non-professionals) if you explain that "This allows you to have a (super) search engine ready to be inserted into the pages of your site." You know that your article is extraordinarily useful, but the reader is not: only by showing real applications and practical examples will you be able to convince him.

No matter how theoretical a topic is: there is always a practical application to explain its benefits. Did you know that Alinghi won the 2003 America's Cup due to the mathematical equations of Navier-Stokes fluid dynamics?

Use figures

They are often the first thing the reader notices along with the title.

Try to insert at least one: a diagram, a photo of the product you are explaining, a screenshot of the software you are programming. "Seeing" what you are talking about is important for the reader, sometimes essential to get his attention. Don't forget to include a meaningful caption, perhaps with an explanation of the contents of the article, for example, in an article on using digital cameras, a (nice) front-page photo with the caption. "Choosing the right aperture for photos is not easy. In the article, you will learn how to get the best out of every condition. “The structure of a good caption is simple: it exposes the problem and immediately after the solution, referring to the reading.

Clarify concepts with examples, similes, and metaphors

Regardless of the type of article, you are writing; do not forget to promptly provide the reader with practical examples that exemplify concepts and theories. This is especially true for the web: many times, the reader is not an expert on the subject, and if the reading becomes too difficult, he will be led to abandon and look for a simpler site.

Examples, similes, and metaphors are the writer's favorite "tools" to facilitate the understanding of concepts. The problem is that to explain a concept, and there are usually many alternatives, not all equally effective: it is up to the author to choose the most suitable.

Keep in mind that a wrong simile will cause the opposite effect: in addition to the danger of falling into style or bordering on the ridiculous, you could choose unintuitive comparisons.

Here is how Piero Angela explains the meaning of "absolute zero":

"To understand the meaning of absolute zero, just keep in mind a very important concept in physics: heat is movement. [...] If you put a pot of water on the fire, after a few minutes, you see that the mass of water moves slightly, and that small currents have been created. Once it reaches 100 degrees, the water, as we know, literally starts to boil.

In a sense, it is in constant motion. If, on the other hand, the pot cools more and more, the water slows down its internal movement, until it becomes calm and, when it reaches zero degrees, it freezes. At that point, everything is still. In a sense, the same happens to matter. The hotter an object is, the more the molecules that compose it stir, "vibrate." And vice versa, the colder it is, the more its molecules slow down the movement. It is evident that this slowing down is not infinite: at a certain point, the molecules by dint of slowing down completely stop. You cannot go further: in fact, the molecules cannot be more still than this.

Just as among various stopped watches, there is not one that is more stationary than the others. This is, in fact, absolute zero: the temperature at which everything still inside matters. This temperature is -273.15 degrees centigrade. "

In this case, the audience was that of a newspaper, therefore heterogeneous: no preparation on the subject could be taken for granted. This is why the author first introduced the basic concept "heat is the movement." And to do this, he chose a concrete example, that of the boiling pot: in this way, images of real situations take shape in the reader's mind, of which he has had direct experience and is able to understand the new concepts by "extrapolation." Only after having trained the reader with the basic notion, does the author explain the meaning of absolute zero with a simile: "as among various stopped clocks, there is not one that is more stationary than the others."

Retouching and final revision

Bibliography

A bibliography is an aspect to be treated very carefully.

If you recommend the right texts and sites, the reader will increase his esteem for you.

A well-done bibliography proves that the author is familiar with the literature on a certain topic: both the reader and the technical reviewer who will review the article will notice. Beware of too much "self-referencing," i.e., inserting too many (and above all irrelevant) references to one's own articles. Forced references achieve the opposite effect to the one just described. The form of the references varies depending on the journal or site.

Revision

After completing the article, allow a few days to pass before re-reading it and doing the final reading. The more time passes, the better, but it is evident that editorial times do not allow you to wait that long.

If you can, let one or more colleagues read the article: having the opinion of strangers is very useful, both for finding technical errors and for improving the structure and style of the contents. The opinion of a stranger is essential because the author fails to see all his mistakes. Technical articles must pass at least one technical review by one or more technical editors or technical reviewers. This review serves to determine if the contents are valid and correct.

After the technical revision, we move on to the stylistic revision to improve the display form. The latter is done by the reviewer himself (especially on the web), or by a non-technical reviewer (all journals have a reviewer for the language and style).

Deliver the article prepared according to the editorial rules provided by the magazine or the website manager. Editors evaluate the author's professionalism not only on the basis of the contents but also on the basis of the "form" of the article, that is, the way in which it is presented. Each magazine has its own editorial rules, usually collected in a document that each author can request at the beginning of the collaboration with the publisher or with the site.

This document lists the characters to be used, the format of the figures, the bibliography, and so on. Sometimes a demonstration article is attached.

Ask the editor for editorial guidelines and follow them to the letter. If they don't exist, ask for a sample article to inspire you. Try to use the same standards and when in doubt (should captions be included below the pictures? Ask the managers in advance: you will make a great impression by showing attention to detail.

Learn from mistakes

No advice is better than experience. When you turn in an article, ask the style reviewer for a copy of the corrections. Revisions are often sent in any case, to be accepted by the author. If possible, before submitting the article for publication, asks the editor to comment on the revisions with explanations: especially at the beginning, and if you write in another language, it will be very useful to avoid falling into error a second time. There is nothing worse than authors who repeat mistakes every time: you will give an impression of laziness and unprofessionalism. Check your mistakes, and if you are in doubt, ask the reason for a correction; again, your penchant for improvement will please the editor and will certainly set you apart from others.

Author: Vicki Lezama