Technical communication is not just one discipline or one profession, but many, which requires a wide range of skills. The main skill associated with technical communication, and perhaps the easiest aspect to explain to someone who is not so familiar with technical communication, is technical writing.
it is not possible to define technical writing adequately in just one or two sentences
Tell someone that you work in technical communication, expect a blank stare. Tell someone that you are a technical writer, you are more likely to receive a knowing nod. Nevertheless, the chances are that the person has no idea what your day looks like and probably thinks that you write college text books. Fair enough: The people who read what technical writers write (the end users), don’t need to know what processes are involved in researching, creating, and finally publishing a piece of technical documentation. But anyone involved in technical communication needs to know precisely what the job entails.
How Does Technical Writing Differ from Other Forms of Writing?
technical writing has distinct characteristics and a defined purpose that make it a genre in its own right
Technical writing is a form of professional writing that is applied to produce technical documentation. Like a novel, technical documentation is a specific genre with special subgenres. Therefore, the grammatical structure, writing style, and wording used in the most common types of software documentation often display similarities. But don’t just take my word for it:
software documentation is just one example of a technical writing genre
Open a software product, for example, Microsoft Notepad, and press F1. Usually, a compressed help file (a .chm file) opens or, depending on what product or version you opened, a Web browser opens. Look at the language used and compare it with the help documentation provided with other software products and by other software companies. Generally speaking, software documentation provided by Microsoft follows defined guidelines, also in translated versions.
most documentation is not written for reading, it is designed for use
Yet the writing conventions used by other software companies are often similar, if not identical – at least in professional software documentation. There is no room for poetic license in technical writing. Documentation is created first and foremost to be used for the purposes of informing, instructing or educating. The act of reading the documentation is secondary; therefore, the writing style should not distract readers from the underlying purpose, hinder them from grasping the meaning of the text, nor prevent them from finding the information they are seeking.
What Is Technical About Technical Writing?
technical writers describe technology
Technical writing is a specialized form of writing because of the technical nature of what it describes: technology and technological devices and developments, for example, in aviation, biotechnology, the chemical industry, IT, industrial manufacturing, various branches of mechanical engineering, the pharmaceutical industry, and medicine.
technical writers work with technology
Furthermore, technical writing is technical because of the way it is developed. Software tools are employed not just to produce, but also to classify, cross-reference, index, link, organize, sort, and reuse text.
technical writers apply practical techniques
Last but not least, like anything technical, technical writing is practical as opposed to theoretical and follows a strict set of rules. Writing guidelines are an important aspect of technical writing.
What Guidelines Apply to Technical Writing?
technical writing guidelines aim to convey the meaning of text in the most effectivee manner
Just to recap: The writing style should not distract readers from the underlying purpose nor hinder readers from grasping the meaning of the text. This means that technical writing must be:
- relevant for the readers, for example, private users generally use products differently to system administrators or might struggle with documentation in English if they are not native speakers of English
- relevant for the purpose of the documentation, for example, marketing language does not belong in a user guide for a product that the user has already bought
- clearly worded using vocabulary and terminology that the target readers are familiar with
- concise and to the point; long sentences are more difficult to read than short sentences
- consistent in content and wording
- standardized with regard to the look and feel and of text
technical writing style focuses on the users’ information needs
If the writing style is not to prevent readers from finding the information they are seeking, technical writing must also be organized, structured, and logical. This can be achieved by considering:
- conventions for titles and headings
- length and number of chapters, sections or topics
- order of chapters, sections, or topics
- cross-referencing, indexing, and linking of information
- lists and tables to present information more clearly
- use of images, such as icons, to support text functions
not all technical writers are willing to comply with guidelines, but compliance with standards and conventions is a necessity that companies cannot afford to ignore
These points can be expanded down to the last comma, semi-colon, and full stop or period (depending on what part of the world you come from) into a comprehensive set of guidelines. To some people, the guidelines for technical writing applied and enforced in various companies seem too rigid and prescriptive. However, guidelines are borne out of necessity to make information accessible and user-friendly and also to comply with industry and legal standards and requirements.
Why Is Some Documentation Written so Badly?
translators are often blamed for poor quality doccumentation, but are not always at fault
In the best case, substandard documentation is the subject of ridicule; in the worst case, it costs product owners and users a great deal of time and frustration. So why is some documentation so bad? The usual suspects are the translators; partly unjustly, partly to rights. Translated versions of documentation are sometimes not just bad, but downright unusable. In some cases, the fault lies with the person who translated the documentation, who is obviously not a translator by trade or vocation. In other cases, translators are given far too little information about the subject matter. For example, translators hardly ever get to see the product being described, so a lot of what they translate is based on guesswork.
subject-matter specialists are not always the best technical writers, nor do they want to be
On the other hand, even good translators have a hard time producing a good translation if the original documentation is difficult to read and understand. Some companies try to reduce costs by giving technical experts such as software developers and engineers the task of writing the documentation. Technical experts are a valuable source of “raw” information, but they do not often have the time nor the inclination to devote themselves to pure documentation tasks like writing. Furthermore, technical experts think technical and write technical. That is, they tend to use a style of language that they and others like them understand. Yet this style of language is not necessarily understood by the target readers.
technical writing is as likely to suffer from poor quality as any other profession if no quality assurance is in place
Poorly written documentation does not follow any guidelines and lacks care and discipline. However, applying guidelines to technical writing is only one way of improving technical documentation. Ideally, all pieces of documentation should undergo quality assurance, for example, in the form of copy editing and proofreading. In an environment where time is money and budget and resources are scarce, quality-assurance measures for technical documentation are neglected and this too can lead to poor documentation.
Is Technical Documentation Important?
documentation is not a necessary evil, but a valuable company asset
“Nobody reads the documentation anyway” is a frequent excuse for producing a small amount of useless text or large volumes of unreadable printed technical literature that is destined to be used as fodder for the office shredder. But there is no excuse for cutting corners; well written technical documentation is important for companies and product owners alike.
documentation promotes internal and external communication and knowledge transfer
For companies, well documented concepts, functions, procedures, processes, and products are an asset. Technical documentation promotes company internal knowledge transfer and can be used for reference for years to come – provided that the information is correct, complete, and comprehensive.
good documentation strategies have company-wide benefits
Well written instructions, guides, and product information ensure that product owners and users become familiar with their purchase quickly and easily. Good technical documentation helps ensure that products are used safely and correctly and can reduce the workload of customer support hotlines – provided that the information is easy to find, easy to read, and easy to understand.
modern communication is about technology and language
In the meantime, large print manuals have been widely, but not wholly, superseded by PDF files. Furthermore, technical documentation is slowly but surely going online. That is, documentation is increasingly distributed over the Internet to be read in a Web browser. This development in technical communication places more demands on technical writing and calls for even greater attention to language style and wording.
Simply said: If you can’t explain something in two sentences, you lose online. You have ten seconds maximum to grab someone’s attention. That is the nature of the Internet and that is what not just technical writers, but also technical communicators at large, have to bear in mind.