Lead Writer: Amanda Butler | Peer Reviewer/s: Felicity Brand, Kieran Morgan | Expert Reviewer/s: Saul Carliner | Managing Editor: Kieran Morgan

This chapter demystifies the roles and responsibilities of technical writers by offering a look into their day-to-day activities and the range of specialties within the profession. You’ll discover the different types of technical writers, understand the documentation they write, and gain insight into the value they bring to organizations. Furthermore, this chapter will touch upon job titles and professional roles that share a foundation with technical writing.

Who Should Read This
• Aspiring Technical Writers • Beginner Technical Writers • Cross-Domain Professionals
Table of Contents: Technical Writing Process
Previous: Chapter 1: Introduction to Technical Writing	Next: Chapter 3: Essential Skills for Technical Writers

1. Introduction

If you’re an aspiring or new technical writer, understanding the options available to you as you contemplate your future career is helpful. Like many other professions, technical writing offers several specializations, some of which might be more suited to your skills, experience, and personal preferences than others—and some of which you might not have known existed. This chapter will help you understand the different specializations and give you a taste of what you can expect in each. We’ll take a deep dive into each specialization, exploring the type of documents they create and who their main audience is.

Whether you’re crafting user-friendly manuals for hardware, getting to grips with a new software product, or interviewing a subject matter expert to create accurate process and procedure documentation, the role of a technical writer is as varied as it is essential. Technical writers are a critical bridge between technology and the end-user, helping to demystify complex concepts into usable prose.

Finally, this chapter will explore the horizon beyond traditional roles, examining the evolving scope for employment in the field and related professional writing opportunities. As the landscape of technical communication continues to shift and expand, so too do the opportunities for those skilled in the art of conveying complex information with clarity.

2. Types Of Technical Writers

There are several categories of technical writer. The tasks and responsibilities will depend on the type of work you are doing:

1. Hardware technical writers create online and printed (and sometimes translated) manuals, typically for end-customer use in manufactured goods.
2. Software technical writers document user interfaces for end users. They typically have some coding experience and understand the software development lifecycle and its tools. They often use structured markup such as Darwin Information Typing Architecture (DITA).
3. Process and procedure technical writers create documentation for an audience that is mostly within (i.e., internal to) the organization they work for. This includes process and procedure-driven documents such as operations manuals, business processes, user guides, and work instructions.

Insight

Developer Documentation Technical Writers A relatively new specialization for software technical writers is the developer documentation technical writer. They are a more “technical” breed of technical writer, as amateur coding skills are a minimum requirement. They follow a “docs-as-code” approach by integrating their documentation into the software code written by developers to create records such as API documentation for a developer audience. They have a strong understanding of the software development lifecycle.

Technical writers will often specialize in one of the above categories, as the toolsets and skills tend to be distinct and often carry a steep learning curve. The necessary soft skills [see below] are of course common across all technical writing types.

3. The Docs They Write

The different types of technical writers create distinct documentation types for different audiences. We’ve provided some basic definitions and examples below.

3.1. Hardware Documentation

Hardware documentation is a type of technical documentation that explains the use or design of a hardware device and its components. This typically includes explanations of its user interface, normal operating limits and specifications, care and maintenance, troubleshooting if something goes wrong, and any safety hazards the customer should be aware of while using the device.

The type of hardware being documented might include anything from personal computers and phones, which have increasingly minimalistic documentation, to complex industrial devices which have nonintuitive interfaces, extensive customization, and troubleshooting that trained operators have to master.

Hardware documentation can be for:

• External users such as customers, end users, or partners using the device. External documentation—particularly that shipped with the device—can be high-profile documents. They often combine the need to help the customer quickly and easily understand a product with the necessity of being a polished piece of visual design that strongly reflects the brand of the company.
• Internal users such as engineers, testers, product managers, and subject matter experts who are involved in designing, building, testing, and validating the product. Documentation written for this audience (such as specifications) will typically have much less of a focus on branding and presentation and more of a focus on accurately communicating technical information and specifications.

Hardware documentation is often subject to stringent regulatory controls, which may differ from country to country and according to the risk profile of the hardware being documented. For example, a surgical device used in the operating theatre will have much more stringent controls on its documentation than a mechanical dog-feeder. Technical writers need to be aware of these regulations. They may mandate small but important details, such as a particular shape of symbol that must be used for warning signs or electrical hazards and particular marks such as the “CE” symbol that indicates that a product has been approved for use within a certain region. When in doubt, you check with a more senior tech writer on your team, or your organization’s regulatory folks.

Examples: Guides, instruction manuals, quick reference guides, guidelines, specifications.

3.2. Software Documentation

Software documentation is a type of documentation that explains the use and design of software and its components. This typically includes explanations of its user interface, how to install it, how to configure it for a customer’s needs, and troubleshooting it if something goes wrong. Even software that you might think is fairly straightforward, such as email, will have extensive documentation and troubleshooting.

Software documentation can be for:

• External users such as customers, end users, or partners using the software. External documentation is usually focused on how to use, install, configure, and troubleshoot the software. These days, it’s most often published on a company’s website or external knowledge base, or it’s integrated into the software itself. The focus is on clarity of instructions, responding to emerging customer questions as they emerge, and keeping the documentation current as new features are released.
• Internal users such as software developers, architects, testers, product managers, and subject matter experts who are involved in designing, building, testing, and validating the software. Documentation for this audience will typically have a focus on the software’s internal architecture.

Examples: User guides, user manuals, end-user documentation, troubleshooting, release notes, specifications.

3.3. Developer Documentation

Developer documentation is a specialized type of software documentation. It helps developers understand how to develop, integrate, and customize software products such as application programming interfaces (APIs) and software development kits (SDKs).

This is a relatively new type of documentation that requires technical writers to have some understanding of programming languages and their associated web tools, such as GitHub, and software engineering processes, such as the software development lifecycle (SDLC).

Developer documentation can be for:

• External users such as customers, partners, and developers who are using or integrating with the software.
• Internal users such as developers, testers, architects, and technical product managers who are involved in creating the software.

Technical writers who work in this area can also be known as Programmer Writers or API Technical Writers.

Examples: API documentation, SDK documentation, reference guides, integration guides.

3.4. Process and Procedure Documentation

Process and procedure documentation includes any document that assists someone in carrying out a process or procedure, whether or not that involves a software component. It might even be a completely manual (nonautomated) business process. Processes can range from something as simple as logging a ticket with your building’s maintenance team for a broken lightbulb to something as complicated as swapping out a nuclear reactor on a submarine.

Process and procedure documentation can be for:

• External users such as vendors, partners, or business-to-business clients of the organization.
• Internal users such as employees; contractors and others within the organization’s workforce; retail, local, or branch office staff; a field workforce employed to carry out installations, inspections, servicing, and so on, for the organization beyond the corporate headquarters; and managers who need to ensure policies are implemented consistently and updated continually to reflect best practice.

Process and procedure documentation typically focuses on clearly communicating the organization’s agreed-on best-practice method and sequence of carrying out a task, or using an internal software system. It’s typically published via an organization’s branded templates, whether that’s in Microsoft Word or a Help Authoring Tool (HAT)’s templated output.

Examples: Procedures, processes, flowcharts, operations manuals, standard operating procedures (SOPs), work instructions.

3.5. Internal vs. External Documentation

In technical writing, documentation is typically categorized as either for internal or external users, each serving distinct purposes and audiences.¹

• External Documentation is created for users outside the organization. These users include customers, end-users, or partners who interact with the organization’s products or services. This documentation often takes the form of user guides, instruction manuals, and troubleshooting resources. It is designed to be accessible and user-friendly, focusing on helping the user understand and effectively use a product or software. External documentation is also a reflection of the organization’s brand and values, often requiring a polished visual design and clear, concise language.
• Internal Documentation, on the other hand, is intended for an audience within the organization. This audience could be employees, contractors, or other stakeholders involved in the design, development, testing, and maintenance of products or services. Examples of internal documentation include technical specifications, process guidelines, and development guides. This type of documentation is more technical and detailed, focusing on accurately communicating internal processes, technical details, and procedural information. It is less concerned with branding and visual design and more focused on precision and clarity of technical content.

Both types of documentation are crucial in their contexts. External documentation serves as a bridge between the product and its users, enhancing user experience and satisfaction. Internal documentation plays a vital role in maintaining operational efficiency and ensuring that products are developed and maintained according to the required standards and specifications.

Understanding the distinction between these two types of documentation is essential for technical writers, as it influences the style, content, and presentation of the information they create.

What Does That Mean?

Internal Documentation Technical content for an organization’s internal audience, focusing on technical details, processes, and operational efficiency. External Documentation User-oriented content for customers and partners outside the organization, emphasizing ease of use, product understanding, and brand representation.

3.6. What’s Driving the Need for All This Documentation, Anyway?

Fundamentally, technical documentation is something that helps a user understand how to carry out a task, whether that’s using a software system or a gadget they’ve just bought. If the software or hardware isn’t 100 percent intuitive—that is, the user can’t figure it out just by using it—then documentation will often be their first port of call.

For any organization that doesn’t want to be flooded by calls to its technical support team, making good, clear documentation easily available for their products is crucial. It helps divert technical support calls, and it mitigates any usability problems with the product that can’t easily be designed away. This is even more important if the product is specialized or complex.

The same goes for process and procedure documentation. As organizations grow larger, they develop their own unique processes and procedures to carry out work in the way they believe is best for their customers. They also want to help their organization save money by doing things the most efficient way. By creating documentation on the best way to carry out these tasks, they accomplish several important goals:

• Standardization: Ensuring tasks are consistently executed.
• Scalability: Preserving the intended ways of working, even as more employees join.
• Efficiency: Streamlining operations while building on past lessons.

Sometimes, the need for documentation is driven by external regulations or best-practice frameworks such as ISO 9001. These frameworks and regulations dictate to the organization which type of documentation it needs—for internal or external audiences, or both. These frameworks may impose extensive hierarchies of documentation that the company needs to create and maintain to comply, and it creates jobs for technical writers like you (if that’s your thing).

Voice of Practitioner

Jerome Role: Technical Writer with 4+ years’ experience and 10+ years’ language and writing tutoring Location: Washington, United States Expertise: Software documentation “I think the biggest misconception of tech writers is that they’re expendable in an organization and don’t provide much value. Docs are among people’s first experience with a product. That initial impression makes a reputation faster than marketing.”

4. A Day in the Life of a Technical Writer

It may surprise you that writing is only one aspect of technical writing. You can only start writing when you understand whom you’re writing for and what you’re writing about. In addition to research, interviews, and writing, technical writing involves collaboration through planning, editing, and more. As your projects progress, as a technical writer, you’ll move from one phase of the technical writing process to another—or more likely, move back and forth between phases as you juggle numerous documentation tasks.

Below is an example of a typical “day in the life” of the different technical writer types, showing all the different tasks they do in their day to achieve their end goal—writing great documentation!

5. Role Names

Technical writers aren’t always called technical writers. In fact, there are many names for our profession, and they vary between countries and even organizations. As experienced technical writers will tell you, some prefer to be called technical communicators, or information architects—the list goes on! Professional bodies in the field are usually called societies for technical communication. The broader term embodies what we do; after all, a key point of this book is that technical writing isn’t just about the writing! It doesn’t always involve the creation of written documents; technical writers may create other forms of content such as e-learning modules, presentations, video tutorials, and technical illustrations. They may even create material with minimal or no text, for example, guides that rely almost exclusively on images rather than words.

Some other names for technical writers include:

• Content designer
• Content strategist
• Digital storyteller
• Documentation manager
• Documentation specialist
• Information architect
• Technical author
• Technical communicator
• Technical editor
• Technical evangelist

Insight

Because technical writing roles can have so many different names, if you only search for “technical writer,” you could limit your potential opportunities. For a broader search, try mixing it up with some of the other job titles shown above. You may find that in your country, another job title is equally as common, or even more so.

6. Other Professional Writing Roles

There are numerous opportunities for professional writers beyond technical writing. Although these roles might not be called technical writers, many of the core hard and soft skills overlap with technical writing. All of them involve a core element of writing and editing competence. If you’ve built up your skills in one professional writing career, great news: you may find it very easy to transition to another with a little additional training or experience.

Here are some examples:

Voice of Practitioner

Francis Role: Technical Writer with 4 years’ experience Location: Manchester, United Kingdom Expertise: Software documentation “I was working in an engineering manufacturing company, where I started as a Trainee Production Operator. I was fixing machines for the automotive industry, doing the physical tooling—it was a hands-on job. During that time I went back to uni on a scholarship with the company to do a STEM degree. In studying, a job came up as a technical writer at my company, and when I applied, they thought I was a good fit because I knew the company, I knew the tools, and I was proving to be literate—I was quite a company guy.”

1. Kassa, D. (2015). Document Control: Lifecycle and the Governance Challenge. Unknown Publisher. p. 9 ↩︎