Technical writing

Last updated

Technical writing is writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, medical, consumer electronics, biotechnology, and forestry. Technical writing encompasses the largest sub-field in technical communication. [1]

Contents

The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating by using technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of how technical the task is". [2]

Overview

Technical writing is performed by a technical writer (or technical author) and is the process of writing and sharing technical information in a professional setting. [3] :4 A technical writer's primary task is to communicate technical information to another person or party in the clearest and most effective manner possible. [3] :4 The information that technical writers communicate is often complex, so strong writing and communication skills are essential. Technical writers not only convey information through text, but they must be proficient with computers as well. Technical writers use a wide range of programs to create and edit illustrations, diagramming programs to create visual aids, and document processors to design, create, and format documents. [4]

While technical writing is commonly associated with online help and user manuals, the term technical documentation can cover a wider range of genres and technologies. Press releases, memos, reports, business proposals, datasheets, product descriptions and specifications, white papers, résumés, and job applications are but a few examples of writing that can be considered technical documentation. [5] Some types of technical documentation are not typically handled by technical writers. For example, a press release is usually written by a public relations writer, though a technical writer might have input on any technical information included in the press release.

History

While technical writing has only been recognized as a profession since World War II, [6] :2 its roots can be traced to classical antiquity. [7] :233 Critics cite the works of writers like Aristotle as the earliest forms of technical writing. [7] :234 Geoffrey Chaucer's work, Treatise on the Astrolabe, is an early example of a technical document. [8] The earliest examples of technical writing date back to the Old English period. [9]

With the invention of the mechanical printing press, the onset of the Renaissance and the rise of the Age of Reason, documenting findings became a necessity. Inventors and scientists like Isaac Newton and Leonardo da Vinci prepared documents that chronicled their inventions and findings. [6] :1 While never called technical documents during their period of publication, these documents played a crucial role in developing modern forms of technical communication and writing. [6]

The field of technical communication grew during the Industrial Revolution. [10] :3 There was an increasing need to provide people with instructions for using the more and more complex machines that were being invented. [10] :8 However, unlike the past, where skills were handed down through oral traditions, no one besides the inventors knew how to use these new devices. Writing thus became the fastest and most effective way to disseminate information, and writers who could document these devices were desired. [10]

During the 20th century, the need for technical writing skyrocketed, and the profession became officially recognized. The events of World War I and World War II led to advances in medicine, military hardware, computer technology, and aerospace technologies. [6] :2 This rapid growth, coupled with the urgency of war, created an immediate need for well-designed documentation to support the use of these technologies. Technical writing was in high demand during this time, and "technical writer" became an official job title during World War II. [6] :1

Following World War II, technological advances led to an increase in consumer goods and standards of living. [6] :3 During the post-war boom, public services like libraries and universities, as well as transport systems like buses and highways, saw substantial growth. The need for writers to chronicle these processes increased. [6] :1 It was also during this period that large business and universities started using computers. Notably, in 1949, Joseph D. Chapline authored the first computational technical document, an instruction manual for the BINAC computer. [11]

The invention of the transistor in 1947 allowed computers to be produced more cheaply and within the purchasing range of individuals and small businesses. [6] :3 As the market for these "personal computers" grew, so did the need for writers who could explain and provide user documentation for these devices. [6] :3 The profession of technical writing saw further expansion during the 1970s and 1980s as consumer electronics found their way into the homes of more and more people. [6]

In recent years, the prominence of computers in society has led to many advances in the field of digital communications, leading to changes in the tools technical writers use. [6] :3 Hypertext, word processors, graphics editing programs, and page layout software have made the creation of technical documents faster and easier, and technical writers of today must be proficient in these programs. [3] :8–9

Techniques

Good technical writing is concise, focused, easy to understand, free of errors, and audience-based. [12] :7 Technical writers focus on making their documents as clear as possible, avoiding overly technical phrases and stylistic choices like passive voice and nominalizations. [3] :236–245 Because technical documents are used in real-world situations, it should always be explicitly clear what the subject matter of a technical document is and how to use the presented information. It would be disastrous if, for example, a technical writer's instructions on how to use a high-powered X-ray machine were difficult to decipher.

Technical writing requires a writer to extensively examine their audience. [3] :84–114 A technical writer needs to be aware of their audience's existing knowledge about the material they are discussing as the knowledge base of the writer's audience determines the content and focus of a document. [3] :84–114 For example, an evaluation report discussing a scientific study's findings that is written to a group of highly skilled scientists will be very differently constructed than one intended for the general public. Technical writers do not have to be subject-matter experts (SMEs) themselves. They often collaborate with SMEs to complete tasks that require more knowledge about a subject than they possess. [3] :51

Technical writing must be accurate. A technical writer, after analyzing their audience, knows what they need to communicate and then needs to convey the message in an accurate and ethical manner. Physical, environmental, or financial repercussions could result if a writer does this incorrectly. Knowing the audience is essential to accuracy because the language will be tailored according to what they already understand about the subject at hand. For example, instructions on how to correctly and safely assemble a bookshelf are included with purchase. Those instructions are constructed so that anyone can follow along, including accurate details as to where each fastener goes. If those instructions were inaccurate, the bookshelf could be unstable and fail. [13]

Document design and layout are also vital components of technical writing. [3] :261–286 Technical writers spend large amounts of time ensuring their documents are readable because a poorly designed document hampers a reader's comprehension. Technical document design stresses proper usage of document design choices like bullet points, font-size, and bold text. [14] Images, diagrams, and videos are also commonly employed by technical writers because these media can often convey complex information, like a company's annual earnings or a product's design features, far more efficiently than text. [3] :306–307

Technical documents

Technical writing covers many genres and writing styles, depending on the information and audience. [3] :84–114 Technical documents are not solely produced by technical writers. Almost anyone who works in a professional setting produces technical documents of some variety. Some examples of technical documentation include:

Tools

The following tools are used by technical writers to author and present documents:

List of associations

Related Research Articles

Markup language Modern system for annotating a document

In computer text processing, a markup language is a system for annotating a document in a way that is visually distinguishable from the content. It is used only to format the text, so that when the document is processed for display, the markup language does not appear. The idea and terminology evolved from the "marking up" of paper manuscripts, which is traditionally written with a red pen or blue pencil on authors' manuscripts. Such "markup" typically includes both content corrections, and also typographic instructions, such as to make a heading larger or boldface.

Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in different roles.

A document management system (DMS) is a system used to receive, track, manage and store documents and reduce paper. Most are capable of keeping a record of the various versions created and modified by different users. In the case of the management of digital documents such systems are based on computer programs. The term has some overlap with the concepts of content management systems. It is often viewed as a component of enterprise content management (ECM) systems and related to digital asset management, document imaging, workflow systems and records management systems.

Adobe FrameMaker Document processor for the production and manipulation of large structured documents

Adobe FrameMaker is a document processor designed for writing and editing large or complex documents, including structured documents. It was originally developed by Frame Technology Corporation, which was bought by Adobe.

Tutorial

A tutorial, in education, is a method of transferring knowledge and may be used as a part of a learning process. More interactive and specific than a book or a lecture, a tutorial seeks to teach by example and supply the information to complete a certain task.

Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance and use. Documentation can be provided on paper, online, or on digital or analog media, such as audio tape or CDs. Examples are user guides, white papers, online help, and quick-reference guides. Paper or hard-copy documentation has become less common. Documentation is often distributed via websites, software products, and other online applications.

A technical writer is a professional information communicator whose task is to transfer information between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. Technical writers research and create information through a variety of delivery media. Example types of information include online help, manuals, white papers, design specifications, project plans and software test plans. With the rise of e-learning, technical writers are increasingly becoming involved with creating online training material.

Technical communication is a means to convey scientific,engineering, or other technical information. Individuals in a variety of contexts and with varied professional credentials engage in technical communication. Some individuals are designated as technical communicators or technical writers. These individuals use a set of methods to research, document, and present technical processes or products. Technical communicators may put the information they capture into paper documents, web pages, computer-based training, digitally stored text, audio, video, and other media. The Society for Technical Communication defines the field as any form of communication that focuses on technical or specialized topics, communicates specifically by using technology or provides instructions on how to do something. More succinctly, the Institute of Scientific and Technical Communicators defines technical communication as factual communication, usually about products and services. The European Association for Technical Communication briefly defines technical communication as "the process of defining, creating and delivering information products for the safe, efficient and effective use of products ".

Audience analysis is a task that is often performed by technical writers in a project's early stages. It consists of assessing the audience to make sure the information provided to them is at the appropriate level. The audience is often referred to as the end-user, and all communications need to be targeted towards the defined audience. Defining an audience requires the consideration of many factors, such as age, culture and knowledge of the subject. After considering all the known factors, a profile of the intended audience can be created, allowing writers to write in a manner that is understood by the intended audience.

A user guide, also commonly known as a user manual, is intended to assist users in using a particular product, service or application. It's usually written by a technician, product developer, or a company's customer service staff.

Website wireframe

A website wireframe, also known as a page schematic or screen blueprint, is a visual guide that represents the skeletal framework of a website. Wireframes are created for the purpose of arranging elements to best accomplish a particular purpose. This discipline is created by L. te Pas. A former student from Harvard (1982). The purpose is usually being informed by a business objective and a creative idea. The wireframe depicts the page layout or arrangement of the website's content, including interface elements and navigational systems, and how they work together. The wireframe usually lacks typographic style, color, or graphics, since the main focus lies in functionality, behavior, and priority of content. In other words, it focuses on what a screen does, not what it looks like. Wireframes can be pencil drawings or sketches on a whiteboard, or they can be produced by means of a broad array of free or commercial software applications. Wireframes are generally created by business analysts, user experience designers, developers, visual designers, and by those with expertise in interaction design, information architecture and user research.

Page layout Part of graphic design that deals in the arrangement of visual elements on a page

In graphic design, page layout is the arrangement of visual elements on a page. It generally involves organizational principles of composition to achieve specific communication objectives.

Professional writing as an activity is writing for reward or as a profession; as a product or object, professional writing is any form of written communication produced in a workplace environment or context that enables employees to, for example, communicate effectively among themselves, help leadership make informed decisions, advise clients, comply with federal, state, or local regulatory bodies, bid for contracts, etc.. For example, in a business office, a memorandum can be used to provide a solution to a problem, make a suggestion, or convey information. Other forms of professional writing commonly generated in the workplace include email, letters, reports, and instructions. In seeking to inform, persuade, instruct, stimulate debate, or encourage action from recipients, skilled professional writers make adjustments to different degrees of shared context, e.g., from a relatively accessible style useful for unsolicited contact letter to prospective clients to a technical report that relies on a highly specialized in-house vocabulary.

Software project management is an art and science of planning and leading software projects. It is a sub-discipline of project management in which software projects are planned, implemented, monitored and controlled.

A specification often refers to a set of documented requirements to be satisfied by a material, design, product, or service. A specification is often a type of technical standard.

Technical translation is a type of specialized translation involving the translation of documents produced by technical writers, or more specifically, texts which relate to technological subject areas or texts which deal with the practical application of scientific and technological information. While the presence of specialized terminology is a feature of technical texts, specialized terminology alone is not sufficient for classifying a text as "technical" since numerous disciplines and subjects which are not "technical" possess what can be regarded as specialized terminology. Technical translation covers the translation of many kinds of specialized texts and requires a high level of subject knowledge and mastery of the relevant terminology and writing conventions.

An API writer is a technical writer who writes documents that describe an application programming interface (API). The primary audience includes programmers, developers, system architects, and system designers.

An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation.

Specification by example (SBE) is a collaborative approach to defining requirements and business-oriented functional tests for software products based on capturing and illustrating requirements using realistic examples instead of abstract statements. It is applied in the context of agile software development methods, in particular behavior-driven development. This approach is particularly successful for managing requirements and functional tests on large-scale projects of significant domain and organisational complexity.

Proposal software also known as proposal management software, proposal writing software, or proposal automation software is a computer program designed to help users develop proposals, presentations, and responses to RFPs. Proposal management software is becoming increasingly popular in companies that manage frequent and extensive proposal writing projects. Such software allows businesses to automate more routine tasks while easily tracking multiple versions.

References

  1. What is Technical Communications? TechWhirl. Accessed December 9, 2014.
  2. "Defining Technical Communication". Society for Technical Communication. Retrieved February 10, 2019.
  3. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Mike Markel (2012). Technical Communication 10th Edition. Bedford/St. Martins.
  4. Johnson, Tom (December 19, 2011). "What Tools Do Technical Writers Use". I'd Rather Be Writing. Retrieved May 4, 2014.
  5. Perelman, Leslie C.; Barrett, Edward; Paradis James. "Document Types". The Mayfield Handbook of Technical & Scientific Writing. Retrieved May 4, 2014.
  6. 1 2 3 4 5 6 7 8 9 10 11 O'Hara, Fredrick M. Jr. "A Brief History of Technical Communication" (PDF). Montana State University Billings. Retrieved April 22, 2014.
  7. 1 2 Doody, Aude; Follinger, Sabine; Taub, Liba (February 8, 2012). "Structures and Strategies in Ancient Greek and Roman Technical Writing: An Introduction" (PDF). Studies in History and Philosophy of Science. University Of Cambridge. 43 (2): 233–236. doi:10.1016/j.shpsa.2011.12.021. Archived from the original (PDF) on August 3, 2012. Retrieved April 22, 2014.
  8. "The Way to the Stars: Build Your Own Astrolabe". Saint John's College. Retrieved April 22, 2014.
  9. Hagge, John (July 1990). "The First Technical Writer in English: A Challenge to the Hegemony of Chaucer". Journal of Technical Writing and Communication. 20 (3): 269–289. doi:10.2190/vwcw-xkmv-949f-vlf7. ISSN   0047-2816.
  10. 1 2 3 Crabbe, Stephen (2012). "Constructing a Contextual History of English Language Technical Writing" (PDF). University of Portsmouth. Archived from the original (PDF) on May 12, 2014. Retrieved April 30, 2014.
  11. "History of Technical Writing". Proedit. 14 September 2012. Retrieved May 9, 2014.
  12. 1 2 3 4 5 6 7 8 Tebeaux, Elizabeth; Dragga, Sam (2010). The Essentials of Technical Communication. Oxford University Press.
  13. Diane Martinez, et. al., "Technical Writing: A Comprehensive Resource of Technical Writers at All Levels."
  14. Waller, Rob (April 2011). "What Makes a Good Document? The Criteria we use" (PDF). The University of Reading: 16–19. Retrieved May 4, 2014.
  15. Perelman, Leslie C., Barrett, Edward, and Paradis James. "Press jaylan peregrino". The Mayfield grave naba Handbook of Technical & Scientific Writing. Retrieved May 4, 2014.
  16. Perelman, Leslie C., Barrett, Edward, and Paradis James. "Specifications." The Mayfield Handbook of Technical & Scientific Writing. Retrieved May 4, 2014.
  17. "Dictionary and Thesaurus | Merriam-Webster". www.merriam-webster.com. Retrieved 2016-01-22.
  18. 1 2 Anderson, Paul V. (2007). Technical Communication [A Reader-Centered Approach] 6th Edition. Thompson Wadsworth.
  19. Johnson, Tom "What Tools Do Technical Writers Use". I'd Rather Be Writing. December 19, 2011. Retrieved May 4, 2014.
  20. "What is LyX". LyX. Retrieved May 9, 2014.
  21. Hewitt, John (January 18, 2005). "How Technical Writers use Microsoft Visio". Poe War. Archived from the original on May 12, 2014. Retrieved May 9, 2014.
  22. Brierley, Sean (2002). Screen Captures 102 (PDF). STC Carolina (Report). pp. 5–8. Retrieved May 9, 2014.
  23. Johnson, Tom (December 19, 2011). "What Tools Do Technical Writers Use". I'd Rather Be Writing. Retrieved May 4, 2014.