How is Technical Writing Different?

There are several factors that set technical writing apart from other types of writing.

TW

Technical writing is characterized by a combination of all these elements. No single characteristic distinguishes technical writing from other kinds of writing. Remember, the saying, beauty lays in the eyes of the beholder. So, it is not surprising that technical writers find beauty in the bland manuals. They can appreciate a well written, usable, useful, and well organized manual, because that’s the beauty of technical writing!

Purpose

Technical writing is directed to a specific set of audience who reads to understand a product, or a concept, or to perform a task. The document should inform, instruct, and educate them. It should contain facts, theories, information, and details that the users look for.

Technical writing is factual, not fictional.

Audience

The users read a document with a purpose to learn, understand, perform certain tasks  and to make certain decisions. They are users of the writing. Hence, you should know about your audience and try to meet their expectations. You have to write what they want and what they they need to know, not what you want or what you may want them to know. Audience is the most important element of effective technical writing.

Technical writing is usually for a specific set of audience.

Language

It takes different level of writing talent to write different kinds of documents. The document should help the readers accomplish the task without them noticing that they were helped along by excellent documentation. Use of language is an important factor that distinguishes it from the other forms of writing.

  • Technical writing involves language that is specific to a particular concept, science, technology, or product. It is informative in nature.

Technical writing is informative, not entertaining.

  • Technical writing is characterized by the information that is accurate, informative, and useful. The language used by literary writers is avoided. You have to choose words carefully and construct sentences that emphasize utility over beauty.

Technical writing emphasizes on utility over beauty.

 Writing Style

Creative writers have their own style and mode of writing and hence, we can often identify the writer by the style of their writing. In comparison to the other forms of writing, technical writing is bland because you have to follow certain do’s and don’ts in terms of writing styles and guidelines when creating technical documents. Technical writing is consistent, organized, logical, systematic, and format specific. The identity of the technical writer is lost to standard stylistic issues, format, and rules.

    • The aim of the writing is to inform and to help the users perform tasks, not to confuse them. Hence, the writing should be clear, accurate, easy to understand, and concise.

Technical writing is concise and to-the-point.

    • It is less creative. You should make consistent use of terminologies, numbers, hyphens, units of measure, punctuation, equations, grammar, symbols, capitalization, and abbreviations. The information and format can be creative when writing marketing material.

Technical writing is logical and consistent.

    • Technical writing is an art because it conveys information to the reader in a way that enables the reader to easily understand the technical information. It is science because it deals with methods, systems, design, theory, and results.

Technical writing is a combination of art and science.

Format

The companies with well-established teams have their own customized style guides, which describes the guidelines and the style issues. They often have a preferred way of writing, organizing, and laying out the content of the technical documents. The writers have to follow the format and stylistic guidelines decided by the organization.

Technical writing is format driven.

Organization

In technical documents, the information has to be organized sequentially and systematically. There has to be a logical sequence to the sections and procedures to reflect the usage and patterns.

Technical writing is systematic, organized, and sequential.

Visual Aids

It is said that a picture is worth a thousand words. The users appreciate a tabular representation of the data or a flow chart instead of wading through lengthy paragraphs. Hence, make use of appropriate visuals aids in the document instead of painting a picture of words. Visual aids help in the following ways:

    • Capturing the attention and interest of the readers
    • Explanation—technical information can often be described better using different types of visual aids (illustrations, snapshots, tables, flow-charts, photographs, graphs) than it can be in words
    • Clarification—to show more about something explained in words so that the users understand the concept faster and clearer, without any confusion.
    • Better understanding—it provides an alternative for those who learn better visually than verbally.

Tone

The tone of the writing is objective and to the point.

    • The procedures are written in an instructive tone
    • Active voice is preferred over passive voice.
    • Sentences are action oriented (Click this…, Press that…, Do this to do that… etc.)

Dependency

Creating a documentation is not a stand alone function—it depends on many factors:

    • The information you receive from the SMEs

You have to depend on the SMEs for getting the document reviewed for technical accuracy. Most of the time, they may not respond to your request for timely review. If the documents are not reviewed on time, the entire documentation schedule gets delayed, due to which the product release also gets delayed.

    • Development of the product

If any functionality of the product is changed, you will have to make the corresponding change to the document. If the product (or a functionality) is not stable, and is in a dynamic state of constant change, you may not be in a position to write that part of the document.

    • The deadline followed by the engineers.
    • The tools and procedures used for documentation

In any case, the writer will be held responsible for the delay for not completing the document on time and will be seen as incapable and inefficient. This problem usually arises when the work of the documentation team is underestimated.

Advertisements

Is Age a Barrier for Technical Writers?

Is age a barrier when hiring technical writers? Well, the answer is—it is and it is not!

When hiring experienced writers, age is definitely not considered. When hiring someone without previous technical writing experience, age sometimes becomes a selection criteria. One of the reason is because after other experience, the expectations of the candidate is much more than a fresher who is relatively younger and inexperienced.

Most of the times, organizations are ready to take in people with no related experience in junior positions and might offer a salary relative to their relevant experience and skills. Those seeking a job may not be able to accept the fact that after being experienced, they are considered to be on the same level as the trainees.

In such a situation, ask yourself if you possess the skills required for this job? Do you have the relevant experience? Why should the organization pay you for the skills and the experience you don’t possess? This will give you an answer why you are recruited at an entry level. You need to be exible and mature in terms of understanding and accepting your limitations. If you are comfortable working with youngsters, in a junior position, for a lesser salary (probably), and if you are con dent of using the skills of your prior working experience to your advantage, age doesn’t really matter.

On a personal perspective, age limit is more of a mental state than physical. If you are eager to learn and grow in the team starting from the basics, age is not a constraint. For that matter, age is not a barrier in any eld if you have the right attitude and if you are mentally and physically fit for the job/work.

Grading Your Audience (Users)

You have to know for whom you are writing for and the degree of their knowledge about the subject. You have to adapt your writing to meet the needs, interests, and the background of the readers. You should perform audience analysis early in the writing process to help clarify how you should organize the information, write, and format your document. To understand the importance of grading and analyzing the audience before you start working on your document, let us consider the following cases:

Case 1: Writing a book—You are writing a book, Introduction to Computers.

  • What you do? You research the topic well and write it, adding a lot of technical information, graphics, and descriptions. You create a book that is technically correct, perfect in language and style, well formatted and designed document. The format and the design of the document is excellent too.
  •  What can happen? It can be rejected by your readers. The audience targeted were children of 6 years of age. They will not understand the technical concepts and hence the information will be of no importance to them. Also, the design and format of the book will not appeal to them!
  • What is the problem? The information is technically correct, but presentation and organization of the information, the level of detail you have to use, the language and style that has to be followed for these two groups of audience are entirely different.
  • Observation: For children in the age group 5-10, you have to include more figures and less text, use simple language, and less technical words. Even if you write a book with the same title for 15-year olds, the content and the structure of the book should be different. This shows the importance of knowing the educational background and knowledge level of your audience before you start writing.

Case 2: Writing a Report—Your organization has developed an electronics device that works as a pacemaker and is supposed to be a breakthrough in medical science. It is cost effective and the patient does not need to undergo a major surgery. You write a report about this new discovery in medical science.

  • What you do? You talk to the people who have created the product and get the required information. You then create a report about the functioning of the device and how helpful it can be to the mankind.
  • What can happen? Your report can be rejected.
  • What is the problem? You wrote for a general audience where as in this case, you have two different sets of users. One set of audience, consisting of engineers, familiar with the electronic concepts, but not with the working of the human heart. Another set consisting of doctors and people related to medical science, who are familiar with the matters of the human heart, but not with the electronics details of the device. Your report did not address the requirement of the two distinct and different set of users.
  • Observation: The two groups have different educational backgrounds and different purposes for reading about the device. The electronics engineers will be more curious about the electronics design and the doctors will be more interested in whether they can safely use this device to treat patients. So, you not only have to provide different background information and details for each type of audience. Ideally, you have to create two reports with different details, to captivate the interest of your audience.

Case 3: Writing a proposal—You are trying to persuade the management in your organization to buy a new but expensive documentation tool.

  • What you do? You research the product and create a proposal that describes the advantages of the software—what the product does.
  • What can happen? Your proposal can be rejected.
  • What is the problem? The information is technically correct, but you did not include the information the readers (the management) are looking for. Your aim is to convince the management that the new software is required for the work you are doing. So the proposal should have addressed the concerns of the management.
  • Observation: You have to justify how the new software can speed up the process. Also, mention how it will take care of the delays and other concerns where you currently spend a few staff-hours on a daily basis. Give examples of how the existing tools affect your flow of work and how the new tool can help you over -come these difficulties. Make a comparative study of the two tools.

Importance of Knowing Your Audience (Users)

Let ‘s begin with a story…

A salesman of a soft drink company was disappointed with a major failure of an assignment in the Middle East. A friend asked, “You are such a good salesman. Why weren’t you successful?”

The salesman explained, “When I got posted in the Middle East, I was very confident that I will make a good sales pitch. Since I did not know Arabic, I planned to convey the message using three posters in the order 1-2-3 and pasted them all over the place.

  • The first poster had a man crawling through the hot desert sand, totally exhausted and panting.
  • The second had the man drinking our soft drink.
  • The third poster showed him totally refreshed.

That should have worked,” said the friend. The salesman replied, “Not only did I not speak Arabic, I also did not realize that Arabs read from right to left. So my posters (which were from left to right) gave a different meaning altogether to the Arabs who were referring the posters in the order 3-2-1.”

So you see, it is very important to know your audience and their requirements! Else, inspite of having all the required information, your efforts in trying to get their attention or helping them will be futile.

The audience are the users who will be using the product and reading your writing. How you write and what you write basically depends on your audience. You have to analyze them to know about their requirements and how you can give it to them. Knowing your audience will help you understand them better and will help you determine the following:

  • The knowledge they have about the subject discussed in the document.
  • The terminology you should use.
  • How simple or complex your writing needs to be.
  • The tone you will have to use when you write. Tone, in writing, refers to how something is explained.

Example: Some marketing errors caused due to lack of audience analysis are listed here:

  • Coors used its slogan, “Turn it loose” in Spanish where it was read as Suffer from diarrhea.
  •  Scandinavian vacuum manufacturer Electrolux used the following slogan in an American campaign: Nothing sucks like an Electrolux.
  • When Gerber started selling baby food in Africa, they used the same packaging as in the US, with the beautiful Caucasian baby on the label. But, it did not sell. Later they learned that in Africa, companies routinely put pictures on the label of what’s inside the package, since most people could not read.
  • Colgate introduced a toothpaste in France called Cue. Unfortunately, cue happened to be the name of a notorious porn magazine in France.
  • An American T-shirt maker in Miami printed shirts for the Spanish market which promoted the Pope’s visit. Instead of “I saw the Pope” (el papa), the shirts read “I saw the potato” (la papa).
  • The Pepsi ad “Come alive with the Pepsi Generation” translated into “Pepsi brings your ancestors back from the grave“, in Chinese.
  • The Coca-Cola name in China was first read as Ke-kou-ke-la, meaning Bite the wax tadpole or female horse stuffed with wax, depending on the dialect. Coke then researched 40,000 characters to find a phonetic equivalent ko-kouko-le, translating into happiness in the mouth.
  • When Parker Pen marketed a ball-point pen in Mexico, its advertisements were supposed to have read, “It won’t leak in your pocket and embarrass you“. The translated advertisement read: “It won’t leak in your pocket and make you pregnant“. The company used the word embarazar which meant to impregnate.

Many years ago, I read somewhere that the academic subject most closely related to technical writing is acting. Then, I did not understand the significance of this statement. Now, I understand it very well. As you are aware, actors must be able to live the character they portray. They must be able to look as the character would, dress as the character would, feel as the character would, and react as the character would.

As a technical writer, you must have the same level of understanding of the person who uses the documentation you write for. You must know what your users know, what they don’t know, and what they expect from the product you are documenting.

Mistakes by Non-Writers: Lack of Audience Analysis

What is common knowledge to a subject matter expert (SME) may not be common knowledge to you or to someone else. Experts in almost any field have difficulty in explaining technical concepts to non-experts without using jargon. Language experts may know the concepts of grammar, but not the technical terminology or concept and may end up writing too much or too little.

Example: Think of how you would communicate with a 6-month old, a two year old, an eight year old, and a 15-year old. Even if you are communicating the same thought/idea to all of them, the way you do it is absolutely different. The tone, the voice, and the words used differ for each of them. You do it to suit the understanding of each of these persons you are talking with.

Documentation written by subject and/or language experts who do not understand the concept of technical writing may contain:

  • Too much detail of the subject for an expert audience.
  • Less detail of the product/subject for a novice user who expects detailed information on the basics of the topic.
  • Technical terms and the writing style used at the wrong levels of understanding.
  • Information what the writer wants to tell the users, not what the users want to know.

The right amount of salt and spices added to a dish makes it a great or bad dish. Similarly, the amount and type of information makes a good or a bad document.

Mistakes by Non-Writers: Not Communicating What is Required

Communication skills is not about just about grammar or writing skills. As a technical writer, your thoughts should be presented in such a way that the person you are communicating to, easily understands what you want them to understand. The most common problems that usually arise in the documents written by non-trained writers (including subject matter experts or language experts) are described here:

Thinking Like the Creators of the Product

Most of the time, the SMEs/engineers are the creators of the products/software.

  • They usually think that people want to know how technology works. Since they themselves have the in-built curiosity or urge to learn the internal operations of the products, they believe that users may want similar information.
  • The engineers know the application too well and are likely to provide technology centric information. This happens because it is probably impossible for them to step back and look at the product from the users point of view.

The users are interested in the task centric information and they usually want to know how to do a particular task or why something should not be done. They may not care about the complexities of the code/product/software.

Making Assumptions

The SME know the product inside out (after all they created it). They are very comfortable with the jargon, assumptions, work arounds, shortcuts, and trouble shooting methods. Hence they make logical assumptions that are not understood by non-experts.

They miss the obvious, forgetting that the users do not perceive the obvious. Writers are not experts and hence they are likely to make the same mistakes and assumptions as the users. They also ask the same dumb questions that the novice users may sometimes ask. Hence, the writers can translate those information into troubleshooting tips, warnings, notes, etc. These dumb questions turn out to be useful information in the document.

Having Specialized Knowledge and Focus

In some cases, the SMEs concentrate on a certain function/feature of the product or software. They do not know much about the other functions or features. If the SMEs are to create the documentation, each would create the documentation for the functionality they are working on (i.e. the part of the product they are familiar with). The result would be a patchy document put together by different individuals.

A technical writer has an overall idea and some knowledge about the entire product and can interweave the information to create accurate and usable user documentation.

Expressing Wrong Information

The most important job of the document is to convey the required information to the users. Unfortunately the subject matter experts express the wrong things and may not document the required information. Not knowing what to document and how to document that makes them poor communicators, not poor language skills.

Problems in Materials Written by Non-writers

Many organizations involve the development engineers to prepare documentation for various reasons—because of limited resources, time constraints, or probably because they don’t understand the importance of documentation. Some of them feel that the engineers know the product/application better than anyone else, so it is better if they create the documents.

Example: The following are some of the prize-winning entries for the Worst Technical Writing Contest held by Metamor Documentation Solutions.

  • Warning label on the side of a cash register:  Before disconnecting, disconnect the connecting connector.
  • The text found in a reference manual of a manufacturing software: To add a part, use Add a Part. Note that you cannot delete a part using Add a Part. To delete a part, use Delete a part.

The trouble with writing is that there are no hard and fast rules or any magic formulae that make it an easy step-by-step task. The truth is, inspite of referring to style guides and procedures to create manuals, you have to re-conceive the rules every time you write because every occasion has its own specific set of requirements and problems. In such situations, the SMEs cannot make a right decision.

Some of the problems in materials written by non-writers are as follows:

Not Communicating What is Required: Click here for details

Lack of Audience Analysis: Click here for details.

Poor Presentation: The most common errors the information presented by untrained technical writers are:

  • Long and complicated sentences, even if they are grammatically correct.
  • Use of lengthy, crammed, and dense paragraphs:
    • When the information should be in a bulleted or numbered list.
    • Where a labeled figure or illustration would have explained the information.
    • Where a table would have done more justice to the job.
    • Lack of white space.
    • Lack of consistency. It is an important factor as it helps to avoid confusion

Poor Organization

The document may be complete and accurate, but it is useless if the users cannot find what they need, when they need it. This happens because the information is not organized properly. The most common errors in organization of information are:

    • Steps are not organized in logical order.
    • Inability to identify between essential and optional information/content.
    • Information not organized in logical and sequential flow.
    • Inappropriate navigational aids, which do not help the users in nding the required topic easily.
    • Section headings not used to logically separate information.
    • Unclear and vague heading (not appropriate to the text it deals about).
    • Sections not describing an idea or concept.

It is extremely easy to recognize a poorly written and badly organized documentation. But, it is equally difficult to prevent it, unless it is done properly.