What is technical writing?
Learn the basics of a common writing career
One of the most common types of business writing is called technical writing. There are many definitions of what technical writing actually is, but some of them are outdated. The definition when I started my career was something like: Documenting the processes required to successfully operate hardware or software applications. When I started my career, we also focused mainly on ginormous printed reference manuals that described each option available in hardware and software. Now, technical writing includes much more.
Technical writing includes any written materials that help people understand how to use hardware and software. Technical writing is generally found in high tech industries such as software and hardware development, information technology (IT), anything engineering related, biotech/medical fields, and so on. However, technical writers also support businesses like appliances, lawn equipment, and even DIY furniture instructions (who do you think writes the IKEA installation instructions for that new bookcase?). Technical writing can include reference material, user guides that step users through a workflow, training documents, technical reports, design documents (that describe how hardware or software will be set up and structured), and even video tutorials (technical writers often write scripts). Of course there aren't many printed documents anymore unless it's a small printed booklet to help someone install hardware that requires plugging things in correctly, but many companies still like to provide PDF files in a format that will look nice if printed. So technical writing can include a vast array of documents.
Thanks for reading Savvy Business Writing! Subscribe for free to receive new posts via email.
What are some examples of technical documents?
Here are some examples I'm familiar with and what they include:
Reference Guides: Steps through the hardware or software and describe every single feature. For an example, a reference guide for Microsoft Word would step through each menu (File, Home, Insert, etc.) and then each option (so for Insert the Insert options, Cover Page, Blank Page, Page Break) and on down the line to the right. Reference Guides also describe every single option in a window or dialog box so users will know what they're for. As an example, here's the Microsoft Word Cross-reference dialog box. A reference guide will provide a description of what cross references are, then describe each option shown in the box. Typically Reference Guides are now used mainly for hardware with a lot of different buttons and options. A reference guide will move across the buttons and options and describe them.
User Guides: Steps through typical workflows for hardware and software. So instead of describing every option in software and hardware as in the example above, a user guide will provide instructions for how to create a cross-reference, starting with how to set up headings, how to add a cross-reference to a document, and how to update it. You can find an example of user guide instructions by looking at online help for software you use at home.
Installation Guide: An installation guide explains how to install something or set something up. Some good examples for documents you might have at home are installation instructions for a home modem, or assembly instructions for your standing desk.
Getting Started Guide: This type of document expands on installation instructions. Some complex hardware and software require people to do a lot of extra tasks to get it ready to use. That might include something like configuring a database. A Getting Started Guide is a way to help users get everything configured and ready to use.
Standard Operating Procedure (SOP): Sometimes companies have very precise ways employees must do certain types of tasks. For employees using software, they might want standard procedures for things like adding new employees to the company database, how to set up family leave, or how to correctly enter inventory. A software SOP will walk users through every single step that's necessary to correctly accomplish a specific task in company software. For companies that work with hardware, or in manufacturing facilities, a SOP will walk user through how to do something very specific with hardware. This could be how to correctly set up switching systems for a telephone company, or how to correctly shut down a complex piece of machinery. These types of SOPs will also include very specific step by step instructions, but also information about personal hazards if you do something wrong (like you might get electrocuted or destroy the equipment).
Job Aids: These are documents to help employees do different jobs correctly. These are often found in manufacturing environments where each job must be done the same way every time to maintain quality control. Job aids usually include lots of photos and drawings to ensure the instructions are clear and employees can quickly determine how to do each job.
Lock Out/Tag Out Instructions (LOTO): This is a type of document unique to companies with electrical equipment or equipment that is inherently dangerous if not used correctly (like manufacturing facilities). A lock out is when an employee needs to lock a piece of dangerous equipment to prepare it for maintenance or cleaning. The idea is that the equipment shouldn't be able to fall on you, or crush you, or electrocute you, so there need to be clear instructions on how to completely disable something and ensure it can't be activated while someone's working on it. The tag-out part describes how to make sure someone not involved in the cleaning or maintenance can't easily reactivate or turn something back on. These are critical safety documents in many companies.
Administrator Guide: Some types of software have administrators who can do things like set user permissions and have access to more options than regular users. Administrator guides describe the extra things that administrators can do. The instructions are usually in "user guide" workflow formats.
Database Setup Instructions: Lots of software and hardware require a connected database. Usually a database expert will set it up, so those types of applications need a separate database guide to tell the database expert what to do.
Design Documents: When engineers design something, both hardware and software, they usually write a design document that describes what it is, how it will be structured, and how it will be built. Often, engineers write these themselves, but sometimes technical writers either collaborate with the engineers on these documents or help with layout and formatting.
Technical Reports: There are all sorts of technical reports technical writers work on. You might be asked to write a report about a project for company executives, for shareholders, or for publication.
Training Instructions: Training materials are very similar to user guide material, but might include sample exercises users can work through to gain experience with a product. These are common with software applications. Technical writers often collaborate with a training team to develop materials. Training materials may also include videos and interactive courses. Technical writers may write scripts or other elements for online training.
That's a list of some I've personally worked on. There are even more than this!
What is a technical writer's role in creating these documents?
Technical writers have to learn all about the technology they are documenting so they can clearly explain the technology to others. That means if you get a job at a software company, you'll need to learn how to use the software. If you get a job at a manufacturing plant, you'll need to learn how workers use each piece of equipment. If you work for a telecommunications company, you'll need to learn how to use all of their devices. This usually requires first tracking down any design documents engineers wrote to figure out what options are available and what they do. For manufacturing facilities, you'll often also be able to dig up technical drawing of machinery to understand how they're put together. Next, you'll need to work with the experts at the company to see how the things work. With software, you can then usually experiment with the software yourself to figure out all of the options. For hardware, you can sometimes get set up in a test lab to experiment with the device yourself. Next, you'll create an outline for what to cover, or you might just follow your department's rules for how to structure a document. Then you'll start writing. Along the way, you'll send drafts to colleagues for review, prepare the documents for distributions (usually somehow online, but sometimes in print), and then make sure the final files are saved.
This is a simplified explanation. The technical documentation workflow varies wildly depending on how big the company is, how much existing documentation they already have, and how many related products there are.
Technical writing includes a wide variety of projects and documents
The main takeaway from this post is that technical writers support a huge range of projects and types of documents. Technical writers need to feel totally comfortable experimenting with technology they know absolutely nothing about, and not be afraid to approach experts to help them understand the technology.
This is a great field for people who love technology and enjoy teaching themselves new skills. Check out other posts for more detailed information about how to create each type of document mentioned in this articles, as well as posts about setting up schedules and other project-related topics.