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 through printed documents or technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".[2]

Transcription

Today we are going to talk about the type
of documents that technical writers create
in the tech industry.
But before we get into that, we need to understand
what is technical writing.
Technical Writing is a part of a bigger
field called Technical Communication.
And Technical Communication
is the practice of communicating
technically complex information to your audience.
The keywords here are: information and audience.
Okay, now that we have this definition,
let's try to apply it to the work that technical writers do.
In my experience, technical writers create
three types of documents in the tech industry:
UI-based docs, Developer docs, and Deployment docs.
Let me explain what they mean.
Let's take an example: YouTube.
YouTube is a software service that allows you
to host and stream videos.
You are watching this video on YouTube, which
makes you a YouTube user.
And as a user, you interact with the YouTube
UI, that is the user interface
to watch, play, like, and share videos, manage your playlists, manage your account,
you know the usual YouTube stuff.
Now the developers of YouTube need
a way to convey this information to their users
So the tech writers at YouTube wrote documents
to help the users navigate the UI.
These docs are what I call UI-based docs.
Now let's say you want to create your own YouTube
channel and upload videos to YouTube.
In that case, you are still a user of the UI, but you are a slightly advanced user.
You need documents to help you understand and navigate the advanced UI
and figure out how to upload videos.
What type of videos can you upload
How to follow the YouTube guidelines, and stuff like that.
So the documents written to help you create your own channel and upload videos
can also be categorized as UI-based docs.
Now let's take it a step further. Suppose you want to create a YouTube app.
In that case, you need more tools
than just the UI.
You need YouTube APIs.
Which help you send requests to YouTube, get data from YouTube
basically integrate your app with YouTube.
The documents written to help you figure out how to integrate your app with YouTube
are called Developer Docs.
API documentation is a subset of Developer
Docs.
Okay, suppose that you have created
an awesome YouTube app
You are ready to launch it, which probably
means you need to host it on a cloud platform.
Let’s say the cloud platform you chose is
DigitalOcean.
In that case, you are dealing with two software products:
You are dealing with YouTube
and you are dealing with DigitalOcean.
Now you need to figure out a way how to make your app work with both of these software products.
For instance, say you want to manage network bandwidth for your users.
You need to figure out the optimal bandwidth that YouTube recommends for its video streaming service
And the optimal bandwidth that DigitalOcean supports.
And then you need to figure those things out and make them match.
And you need to refer to the documentation of both YouTube and DigitalOcean to figure that out.
The docs written to help you make these decisions and figure out the deployment process
are what I call Deployment docs.
To recap, technical writers in the software industry work on three types of documents:
UI-based docs, Developer docs, and Deployment docs
As a tech writer, you might end up working on
only one of these docs, or all of them.
For example, I work on all three types of
documents at work:
I work on the documentation of our distributed SQL database
I create docs to help our users navigate the Admin UI (which are the UI-based docs).
I also work on docs to help our users use our SQL APIs to build apps (which are API docs or Developer docs)
And I also work on docs to help our users about deploy and secure the apps on cloud platforms
(which are Deployment docs).
So that’s what I do at work - I help our users use our awesome product
to create even more awesome products.
Best job in the world!

Contents

Overview

Technical writing is performed by a technical writer (or technical author) and is the process of writing and sharing information in a professional setting.[3]:4 A technical writer's primary task is to convey information to another person or party in the most clear and effective manner possible.[3]:4 The information that technical writers convey is often complex, and it is one of their main tasks to analyze the information and present it in a format that is easy to read and understand.[3]:12–14A good technical writer needs strong writing and communication skills. They do not only convey information through text, and must be proficient with computers as well. They 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]

With the invention of the mechanical printing press, the onset of the Renaissance and the rise of the Age of Reason, the need to document findings became a necessity, and 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.[9]:3 This increased the need to instruct people how to use the more and more complex machines that were being invented and used.[9]: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.[9]

During the 20th century, the need for technical writing skyrocketed, and the profession finally 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 and written documents that chronicled the use of these technologies. Technical writing was in high demand during this time, and 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 massive amounts of growth, and the need for writers to chronicle these processes increased.[6]:1 It was also during this period that computers started being used in large businesses and universities. Notably, in 1949, Joseph D. Chapline authored the first computational technical document, an instruction manual for the BINAC computer.[10]

The discovery of the transistor in 1947 allowed computers to be produced more cheaply than ever before.[6]:3 These cheaper prices meant that computers could now be purchased by individuals and small businesses.[6]:3 And as a result of the computer's growing prominence, the need for writers who could explain and document these devices grew.[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 many changes in the tools technical writers use.[6]:3Hypertext, word processors, graphics editing programs, and page layout software have made the creation of technical documents faster and easier than ever before, 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 is audience-based.[11]: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 what should be done with 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 will determine 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 and generally 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 are trying to communicate. The goal from there is 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 important to accuracy because the language will be tailored according to what they understand about the subject at hand. For example, instructions on how to correctly and safely build a bookshelf are included when purchased. Those instructions are constructed so that anyone could follow along, including accurate details as to where each fastener goes. If those instructions were inaccurate, the bookshelf could be unstable and fail.[12]

Document design and layout are also very important 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.[13] 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 writing include:

Instructions and procedures are documents that help either developers or end users operate or configure a device or program.[11]:226 Examples of instructional documents include user manuals and troubleshooting guides for computer programs, computer hardware, household products, medical equipment, mechanical products and automobiles.

Proposals. Most projects begin with a proposal—a document that describes the purpose of a project, the tasks that will be performed in the project, the methods used to complete the project, and finally the cost of the project.[11]:191 Proposals cover a wide range of subjects. For example, a technical writer may author a proposal that outlines how much it will cost to install a new computer system, a marketing professional may write a proposal with the product offerings and a teacher may write a proposal that outlines how a new biology class will be structured.

Emails, letters, and memoranda are some of the most frequently written documents in a business.[11]:117 Letters and emails can be constructed with a variety of goals—some are usually aimed at simply communicating information while others are designed to persuade the recipient to accomplish a certain task. While letters are usually written to people outside of a company, memoranda (memos) are documents written to other employees within the business.[11]:118

Press releases. When a company wants to publicly reveal a new product or service, they will have a technical writer author a press release, a document that describes the product's functions and value to the public.[14]

Specifications are design outlines that describe the structure, parts, packaging, and delivery of an object or process in enough detail that another party can reconstruct it.[15] For example, a technical writer might diagram and write the specifications for a smartphone or bicycle so that a manufacturer can produce the object.

Descriptions are shorter explanations of procedures and processes that help readers understand how something works.[3]:564 For example, a technical writer might author a document that shows the effects of greenhouse gases or demonstrates how the braking system on a bike functions.

Résumés and job applications are another example of technical documents.[11]:284–285 They are documents that are used in a professional setting to inform readers of the author's credentials.

Technical reports are written to provide readers with information, instructions, and analysis on tasks.[11]:141–143 Reports come in many forms. For example, a technical writer might evaluate a building that is for sale and produce a trip report that highlights his or her findings and whether or not he or she believes the building should be purchased. Another writer who works for a non-profit company may publish an evaluation report that shows the findings of the company's research into air pollution.

Case study is a published report about a person, group, or situation that has been studied over time; also : a situation in real life that can be looked at or studied to learn about something.[16] For example, an individual's challenging situation at his or her workplace and how he or she resolved it is a case study.

White papers are documents that are written for experts in a field and typically describe a solution to a technological or business challenge or problem.[11]:644 Examples of white papers include a piece that details how to make a business stand out in the market or a piece explaining how to prevent cyber-attacks on businesses.

Websites. The advent of hypertext has changed the way documents are read, organized, and accessed. Technical writers of today are often responsible for authoring pages on websites like "About Us" pages or product pages and are expected to be proficient in web development tools.[17]:484–504

Datasheets are the document that summarize the features, key specifications, technical characteristics, application circuits and some other important information about the product, machine, equipment, software, application, system in brief.

Tools

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

Desktop publishing tools or word processors. Word processors such as Scrivener, Microsoft Word, Apple Pages, and LibreOffice Writer are used by technical writers to author, edit, design, and print documents. Since technical writing is as much about the page's layout as it is the written language, enhanced desktop publishing tools such as Adobe InDesign and LyX are also used by Technical Writers.[18] These programs function similarly to word processors but provide users with more options and features for the document's design and automate much of the formatting.[19]

Help authoring tools are used by technical writers to create the help systems that are packaged with software products, delivered through web browsers or provided as files users can view on their computers.[20] Examples are Madcap Flare and Adobe Framemaker. When writing instructional procedures to describe mechanical, electrical or software programs; technical writers will use these tools to assist them in simplifying assembly, operation or installation processes.

Image editing software. Often, images and other visual elements can portray information better than paragraphs of texts.[3]:306–307 In these instances, image editing software like Adobe Photoshop and GIMP are used by technical writers to create and edit the visual aspects of documents like photos, icons, and diagrams.

Collaborative software programs. Because technical writing often involves communication between multiple individuals who work for different companies, it can be a collaborative affair.[3]:57 Thus, technical writers use Wiki Systems and shared document work-spaces to work with other writers and parties to construct technical documents.[3]:74

Web development tools. Technical writers' jobs are no longer limited to just producing documents. They must now also produce content for company's corporate and other professional web sites.[17]:485 Web Development Tools like Adobe Dreamweaver are standard tools in the industry that technical writers are expected to be proficient in.

Graphing software. In order to portray statistical information like the number of visits to a restaurant or the amount of money a university spends on its sporting programs, technical writers will use graphs and flowcharts.[3]:306–307 While programs like Microsoft Excel and Word can create basic graphs and charts, sometimes technical writers must produce incredibly complex and detailed graphs that require functions not available in these programs. In these instances, powerful graphing and diagramming tools like Microsoft Visio are used to effectively organize and design graphs and diagrams.[21]

Screen capture tools Technical writers commonly use Screen Capture Tools like Camtasia and Snagit to capture their desktops.[22][23] When creating instructions for computer software, it's much easier for a technical writer to simply record themselves completing a task than it is to write a lengthy series of instructions that describe how the task must be performed. Screen capture tools are also used to take screenshots of programs and software running on user's computers and then to create accompanying diagrams.