Technical writing
Encyclopedia
Technical writing, a form of technical communication
, is a style of writing used in fields as diverse as computer
hardware
and software, engineering
, chemistry
, the aerospace industry
, robotics
, finance
, consumer electronics
, and biotechnology
.
Technical writer
s begin by forming a clear understanding of the purpose of the document they will create.If payment for production comes from a second party, this includes a detailed interview with the party that pays for the document's production. Technical writers then typically go on to gather information from existing documentation and from subject matter experts. A subject matter expert
(SME) is any expert on the topic that the writer is working on. Technical writers are often not SMEs themselves (unless they are writing about creating good technical documentation). Workers at many levels, and in many different fields, have a role in producing technical communications. A good technical writer needs strong language and teaching skills and must understand the many conventions of modern technical communications.
Advanced technical writers often move into specialized areas such as API writing, document architecture or information management.
Procedural technical writing translates complex technical concepts and instructions into a series of simple steps that enable users to perform a specific task in a specific way. To present appropriate information, writers must understand the audience and their goals.
Persuasive technical writing attempts to sell products or change behaviors by putting forth compelling descriptions of how a product or service can be used in one's life. This type of writing often delves into features and benefits of the product or service, and may use illustrations to make the benefits easier for the audience to understand.
(STC).
It is also important to understand the medium typically used to view the final product. An HTML document (web page), viewed through a browser, has different presentational possibilities from the printed page - most noticeably hyperlinks and animation - that can really enhance the readers' experience.
Consider a technical writer writing a cake recipe:
The three C's of good technical writing are:
Clear, concise, and complete writing helps the reader to grasp the meaning quickly.
The technical writer determines that the recipe is written on the back of a napkin but is partially indecipherable, so he or she must also interview a subject-matter expert (SME)—the chef who created it. On being told that the audience consists of people in their own kitchens, the writer adjusts the writing style accordingly and replaces or defines terms such as "beurre mixer" or "springform pan," which may be more suited to an audience of highly trained chefs. The chef reviews a draft of the recipe (a technical edit) and notates corrections (bake at 350 degrees, not 325 degrees). The writer prepares a final draft, which the document owner and any other stakeholders review and approve before it is published in one or more formats, such as a paper or HTML. Different versions of the document might also be published to meet the needs of different audiences. For example, the version intended for an American audience will use imperial measurements, whereas other versions will use metric measurements. Rather than creating an entirely new document for each audience, the technical writer will create a single document, and use variables and other methods to manage the differences.
Broadly speaking, technical documentation can be categorized into three types, depending on the style of writing, the level of knowledge transferred and the target audience.
Technical art is also considered a form of technical communication.
Technical writing is often associated with online help
and user manuals. However, technical writers create many other forms of technical content. These include product release notes
, product troubleshooting
guides, product user guide
s, tutorials, software installation guides, API programmers' guides
, legal disclaimers, policies and procedures
, business proposals
, and white paper
s. Technical writing specifically in support of software applications is commonly referred to as user assistance
.
Technical communication
Technical communication is a method of researching and creating information about technical processes or products directed to an audience through media. The information must be relevant to the intended audience. Technical communicators often work collaboratively to create products for various...
, is a style of writing used in fields as diverse as computer
Computer
A computer is a programmable machine designed to sequentially and automatically carry out a sequence of arithmetic or logical operations. The particular sequence of operations can be changed readily, allowing the computer to solve more than one kind of problem...
hardware
Hardware
Hardware is a general term for equipment such as keys, locks, hinges, latches, handles, wire, chains, plumbing supplies, tools, utensils, cutlery and machine parts. Household hardware is typically sold in hardware stores....
and software, engineering
Engineering
Engineering is the discipline, art, skill and profession of acquiring and applying scientific, mathematical, economic, social, and practical knowledge, in order to design and build structures, machines, devices, systems, materials and processes that safely realize improvements to the lives of...
, chemistry
Chemistry
Chemistry is the science of matter, especially its chemical reactions, but also its composition, structure and properties. Chemistry is concerned with atoms and their interactions with other atoms, and particularly with the properties of chemical bonds....
, the aerospace industry
Aerospace
Aerospace comprises the atmosphere of Earth and surrounding space. Typically the term is used to refer to the industry that researches, designs, manufactures, operates, and maintains vehicles moving through air and space...
, robotics
Robotics
Robotics is the branch of technology that deals with the design, construction, operation, structural disposition, manufacture and application of robots...
, finance
Finance
"Finance" is often defined simply as the management of money or “funds” management Modern finance, however, is a family of business activity that includes the origination, marketing, and management of cash and money surrogates through a variety of capital accounts, instruments, and markets created...
, consumer electronics
Consumer electronics
Consumer electronics are electronic equipment intended for everyday use, most often in entertainment, communications and office productivity. Radio broadcasting in the early 20th century brought the first major consumer product, the broadcast receiver...
, and biotechnology
Biotechnology
Biotechnology is a field of applied biology that involves the use of living organisms and bioprocesses in engineering, technology, medicine and other fields requiring bioproducts. Biotechnology also utilizes these products for manufacturing purpose...
.
Technical writer
Technical writer
A technical writer is a professional writer who designs, creates, and maintains technical documentation...
s begin by forming a clear understanding of the purpose of the document they will create.If payment for production comes from a second party, this includes a detailed interview with the party that pays for the document's production. Technical writers then typically go on to gather information from existing documentation and from subject matter experts. A subject matter expert
Subject Matter Expert
A subject matter expert or domain expert is a person who is an expert in a particular area or topic. When spoken, sometimes the acronym "SME" is spelled out and other times voiced as a word ....
(SME) is any expert on the topic that the writer is working on. Technical writers are often not SMEs themselves (unless they are writing about creating good technical documentation). Workers at many levels, and in many different fields, have a role in producing technical communications. A good technical writer needs strong language and teaching skills and must understand the many conventions of modern technical communications.
Advanced technical writers often move into specialized areas such as API writing, document architecture or information management.
Communicating with the audience
Audience analysis is a key feature of all technical writing. Technical writing is a communication to convey a particular piece of information to a particular audience for a particular purpose. It is often an exposition about scientific subjects and technical subjects associated with finance, construction, medicine, agriculture, technology, and various sciences.Procedural technical writing translates complex technical concepts and instructions into a series of simple steps that enable users to perform a specific task in a specific way. To present appropriate information, writers must understand the audience and their goals.
Persuasive technical writing attempts to sell products or change behaviors by putting forth compelling descriptions of how a product or service can be used in one's life. This type of writing often delves into features and benefits of the product or service, and may use illustrations to make the benefits easier for the audience to understand.
History
The origins of technical writing have been variously attributed to antiquity. However, a clear trend towards the discipline can be seen starting from the time of World War I, growing out of the need for technology-based documentation in the military, manufacturing, electronics, and aerospace industries. In 1953, two organizations concerned with improving the practice of technical communication were founded in the United States of America: the Society of Technical Writers, and the Association of Technical Writers and Editors. These organizations merged in 1957 to form the Society of Technical Writers and Editors, a predecessor of the current Society for Technical CommunicationSociety for Technical Communication
The Society for Technical Communication is a professional society for the advancement of the theory and practice of technical communication.-Overview:...
(STC).
Technical writing is presentational
Technical writing involves attractive layout for easy reading and comprehension. Presentational strategies help readers to grasp messages quickly.- The top-down strategy (tell them what you will say, then say it)
- Headings (like headlines in newspapers)
- Chunks (short paragraphs)
- Plain, objective style so that readers can easily grasp details.
It is also important to understand the medium typically used to view the final product. An HTML document (web page), viewed through a browser, has different presentational possibilities from the printed page - most noticeably hyperlinks and animation - that can really enhance the readers' experience.
Overview
For technical documents to be useful, readers must be able to understand and employ them without having to decode wordy and ambiguous prose. Good technical writing clarifies technical jargon; that is, it presents useful information that is clear and easy to understand for the intended audience. Poor technical writing may increase confusion by creating unnecessary technical jargon, or failing to explain unavoidable technical terms that readers would not be expected to be familiar with.Consider a technical writer writing a cake recipe:
- Audience: Is the audience composed of people in home kitchens or highly trained chefs in professional kitchens?
- Source: Is there existing documentation—a rough draft? Who is the subject matter expert (SME)?
- Deliverable: Is the deliverable simple text for inclusion in a book, or formatted to final form? Is the target a paper, a Web page, or something else?
The three C's of good technical writing are:
- Clear
- Concise
- Complete
Clear, concise, and complete writing helps the reader to grasp the meaning quickly.
The technical writer determines that the recipe is written on the back of a napkin but is partially indecipherable, so he or she must also interview a subject-matter expert (SME)—the chef who created it. On being told that the audience consists of people in their own kitchens, the writer adjusts the writing style accordingly and replaces or defines terms such as "beurre mixer" or "springform pan," which may be more suited to an audience of highly trained chefs. The chef reviews a draft of the recipe (a technical edit) and notates corrections (bake at 350 degrees, not 325 degrees). The writer prepares a final draft, which the document owner and any other stakeholders review and approve before it is published in one or more formats, such as a paper or HTML. Different versions of the document might also be published to meet the needs of different audiences. For example, the version intended for an American audience will use imperial measurements, whereas other versions will use metric measurements. Rather than creating an entirely new document for each audience, the technical writer will create a single document, and use variables and other methods to manage the differences.
Types of technical documents
Technical writers use computers and other electronic communications equipment extensively in performing their work. They also work regularly with publishing software and various authoring environments to prepare material directly for the Internet. Technical writers frequently work with word processing, graphic design, page layout, and multimedia software. The nature of technical writing is evolving, and modern technical writers combine text, graphics, images, and sound into their work.Broadly speaking, technical documentation can be categorized into three types, depending on the style of writing, the level of knowledge transferred and the target audience.
- End user assistance. These information products help a user understand how to use a technical software or hardware product. User manuals for computer software, hardware, household products, medical equipment, cell phones, SmartPhones, and other consumer electronics belong to this category.
- Traditional technical documentation. Here the objective of the writer is to communicate with a specific audience. Maintenance guides, appliance/application repair manuals, engineering specifications, research papers, works of reference, annual reports. and articles written for technical journals (to name a few examples) belong in this category.
- Marketing communication. Product catalogs, brochures, advertisements, introductory pages for web sites, press releases, and ad copy belong in this category.
Technical art is also considered a form of technical communication.
Technical writing is often associated with online help
Online help
Online help is topic-oriented, procedural or reference information delivered through computer software. It is a form of user assistance. Most online help is designed to give assistance in the use of a software application or operating system, but can also be used to present information on a broad...
and user manuals. However, technical writers create many other forms of technical content. These include product release notes
Release notes
Release notes are documents that are distributed with software products, often when the product is still in the development or test state...
, product troubleshooting
Troubleshooting
Troubleshooting is a form of problem solving, often applied to repair failed products or processes. It is a logical, systematic search for the source of a problem so that it can be solved, and so the product or process can be made operational again. Troubleshooting is needed to develop and...
guides, product user guide
User guide
A user guide or user's guide, also commonly known as a manual, is a technical communication document intended to give assistance to people using a particular system...
s, tutorials, software installation guides, API programmers' guides
API Writer
An API writer is a technical writer who writes documents that describe an application programming interface . The primary audience includes programmers, developers, system architects, and system designers.- Overview :...
, legal disclaimers, policies and procedures
Policies and Procedures
Policies and procedures are a set of documents that describe an organization's policies for operation and the procedures necessary to fulfill the policies...
, business proposals
Proposal (business)
A business proposal is a written offer from a seller to a prospective buyer.Business proposals are often a key step in the complex sales process—i.e., whenever a buyer considers more than price in a purchase.-Overview:...
, and white paper
White paper
A white paper is an authoritative report or guide that helps solve a problem. White papers are used to educate readers and help people make decisions, and are often requested and used in politics, policy, business, and technical fields. In commercial use, the term has also come to refer to...
s. Technical writing specifically in support of software applications is commonly referred to as user assistance
User Assistance
User assistance is a general term for guided assistance to a user of a software product. The phrase incorporates all forms of help available to a user. Assistance can also automatically perform procedures or step users through the procedure, depending on the question that the user asked...
.
Associations
- Society for Technical CommunicationSociety for Technical CommunicationThe Society for Technical Communication is a professional society for the advancement of the theory and practice of technical communication.-Overview:...
- IEEE Professional Communication SocietyIEEE Professional Communication SocietyThe ' is a professional society of the IEEE.- History :Formed in March of 1957 as the IRE Professional Group on Engineering Writing, the group changed its name to the IRE Professional Group on Engineering Writing and Speech , IEEE Professional Technical Group on Engineering Writing and Speech ,...
- SIGDOCSIGDOCSIGDOC is the Special Interest Group on Design of Communication of the Association for Computing Machinery .-Mission:The mission of SIGDOC includes:* Promoting the professional development of its members....
Special Interest Group on Design of Communication - Institute of Scientific and Technical CommunicatorsInstitute of Scientific and Technical CommunicatorsThe Institute of Scientific and Technical Communicators is the UK's professional association for those involved in technical communication...
(UK-based) - Association for Business CommunicationAssociation for Business CommunicationThe Association for Business Communication is the primary academic organization for the field of business communication scholarship, research, education and practice...
- Czech Society for Technical Communication (Cz-based)
- TekomTekomTekom Technologies, Inc. is a Taiwanese consumer electronics company, founded in 1996. Its headquarters are in Taipei, and it has an office in Shanghai and a factory in Guangdong....
Professional organization for technical communication, Germany
See also
- EditingEditingEditing is the process of selecting and preparing written, visual, audible, and film media used to convey information through the processes of correction, condensation, organization, and other modifications performed with an intention of producing a correct, consistent, accurate, and complete...
- Instructional designInstructional designInstructional Design is the practice of creating "instructional experiences which make the acquisition of knowledge and skill more efficient, effective, and appealing." The process consists broadly of determining the current state and needs of the learner, defining the end goal of instruction, and...
- Creative nonfictionCreative nonfictionCreative nonfiction is a genre of writing that uses literary styles and techniques to create factually accurate narratives. Creative nonfiction contrasts with other nonfiction, such as technical writing or journalism, which is also rooted in accurate fact, but is not primarily written in service...
- Introduced error