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

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.

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.

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.

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.

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.

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.”

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