In 2019, a major cloud provider released a new authentication API. The product worked. The underlying security model was sound. The implementation was correct. Developers who tried to use it could not.

The documentation assumed familiarity with concepts that most developers did not have. The tutorial jumped to advanced configuration before establishing basics. The error messages referenced internal terminology without explanation. The reference documentation existed but was disorganized. Six months after launch, adoption was a fraction of what internal projections had predicted.

A technical writer was brought in. Within four months, the documentation had been restructured. Tutorials walked beginners through working examples. Troubleshooting guides addressed the most common errors with concrete solutions. Developer adoption increased substantially without any changes to the product itself.

The product had not changed. The documentation had. This is what technical writing does.

What Technical Writing Is

Technical writing is the practice of creating documentation that communicates specialized, complex information to audiences who need to understand or use it.

The defining characteristic is not the subject matter — technical writing covers software, engineering, medicine, science, finance, law, and any domain with specialized knowledge — but the purpose: to enable the reader to do something, understand something, or find something, as efficiently and accurately as possible.

Technical writers are translators. They translate information from the people who build things — engineers, scientists, product managers, researchers — into documents that the people who use those things can act on. They bridge the gap between expertise and application.

The Scope of Technical Writing

Technical writing encompasses a wide range of document types:

Document Type	Purpose	Primary Audience
User guides	Help users operate a product or system	End users
API documentation	Enable developers to integrate a system	Developers
Installation guides	Walk users through setup processes	Technical users
Tutorials	Teach through hands-on examples	Learners
Reference documentation	Describe the system accurately and completely	Users looking up specific information
White papers	Explain a technology, approach, or finding	Decision-makers, technical evaluators
Standard operating procedures	Specify how processes must be performed	Employees, operators
Release notes	Document what changed in a product update	Existing users, developers
Runbooks	Enable operational response to incidents	Site reliability engineers, operators
Training materials	Prepare users to perform tasks	New users, trainees

The line between technical writing and other writing disciplines is not sharp. Technical writers overlap with UX writers (who write interface text), content strategists (who plan content across a product), knowledge management specialists, and learning and development professionals.

The Divio Documentation Framework

One of the most influential frameworks for thinking about technical documentation was developed by Daniele Procida at the company Divio and presented at PyCon Australia in 2017. The Divio documentation system — also called the "four types of documentation" or the "documentation quadrant" — argues that most documentation confusion arises from conflating documents with different purposes.

The framework divides all documentation along two axes:

• Practical vs. theoretical (doing vs. understanding)
• Learning vs. working (acquisition vs. application)

These produce four distinct documentation types:

Tutorials (Learning + Practical)

Tutorials are learning-oriented. Their purpose is to take a complete beginner through an experience that teaches them the product by doing.

The defining characteristic of a tutorial is that it produces a working outcome. The reader starts from nothing and ends having built or accomplished something real. The tutorial does not explain everything — it is selective, simplified, and encouraging. Getting the learner to a working state is the goal; completeness is secondary.

Tutorials are analogous to a cooking lesson where the chef guides you through making a dish. You are not expected to understand food science. You are expected to produce something edible and to feel capable of returning to the kitchen.

Good tutorial writing:

• Starts from zero — assume nothing
• Produces a working result at every step
• Does not explain why in depth — "do this; now do this"
• Is encouraging and reassuring
• Minimizes decision points

How-to Guides (Working + Practical)

How-to guides are goal-oriented. Their purpose is to help someone who already understands the basics accomplish a specific real-world task.

The analogy is a recipe: the reader knows what cooking is, knows they want to make risotto, and needs a reliable sequence of steps to achieve that goal. The recipe does not teach them to cook; it guides them to a specific outcome.

How-to guides assume competence and context. They answer the question "how do I do X?" for a user who already knows what X is and why they want to do it.

Good how-to writing:

• Focuses on the task, not the system
• Assumes the reader knows the basics
• Lists prerequisites clearly
• Provides numbered steps in order
• Addresses common variations and errors

Reference (Working + Theoretical)

Reference documentation is information-oriented. Its purpose is to describe the system accurately and completely. It is the documentation users consult when they need a specific fact about how something works.

An API reference is the canonical example: for every endpoint, every parameter, every response code, every error — accurate, complete, consistent documentation. A user who needs to know what parameters the authentication endpoint accepts goes to the reference. They are not learning; they are looking something up.

Good reference writing:

• Is complete and accurate — missing information fails users
• Is consistent in structure across entries
• Is neutral — no tutorials, no opinions
• Is well-organized for navigation, not for reading
• Is up to date (stale reference documentation is worse than no documentation)

Explanation (Learning + Theoretical)

Explanatory documentation is understanding-oriented. Its purpose is to deepen the reader's conceptual grasp of the subject — to help them understand why something is the way it is, the context that produced it, the alternatives that exist, the tradeoffs that were made.

Explanation does not teach through doing (that is tutorials) and does not describe how (that is reference). It illuminates context, history, rationale, and concept. "Why does this system use eventual consistency instead of strong consistency?" is an explanation question. The answer does not help the user do anything immediately — it helps them understand deeply enough to make good decisions.

Good explanation writing:

• Provides context and background
• Discusses alternatives and tradeoffs
• Explains rationale, not just facts
• Links to related concepts
• Is not a tutorial or reference in disguise

"The reason documentation fails is almost always that different types of documentation have been mixed together. The writer tries to explain while also providing reference information while also teaching through doing while also providing how-to instructions. The reader cannot find what they need because everything is mixed with everything else." — Daniele Procida, Divio Documentation System

Docs-as-Code: How Modern Technical Documentation Works

The technical documentation field has been significantly transformed by the docs-as-code movement — a philosophy and set of practices that treats documentation with the same tools and workflows as software development.

The Core Idea

Before docs-as-code, technical documentation was typically managed in proprietary tools: Adobe RoboHelp, MadCap Flare, Microsoft Word, Confluence, or similar systems. Documents lived in formats that were not version-controlled, difficult to review systematically, or hard to automate.

Docs-as-code moves documentation to:

Plain text markup languages: Primarily Markdown or reStructuredText. These are simple, human-readable formats that can be stored in any version control system, compared using standard diff tools, and rendered into polished output.

Version control (Git): Documentation lives in Git repositories alongside (or adjacent to) the code it documents. Every change is tracked. Every version is recoverable.

Pull request review workflows: Documentation changes go through the same review process as code changes. Engineers review docs for technical accuracy. Other writers review for style and clarity. Stakeholders review before publication.

Automated build and publish pipelines: Documentation builds automatically when changes are merged — to internal staging for review and to public documentation sites for publication. Tools like Sphinx, MkDocs, Docusaurus, and Jekyll convert plain text files into polished documentation sites.

Why Docs-as-Code Matters

Collaboration: Engineers are comfortable with Git, Markdown, and pull requests. Docs-as-code removes the barrier to engineering contributions to documentation. Engineers can fix documentation errors directly rather than filing tickets for technical writers.

Accuracy: Documentation that lives next to code and changes with it stays more accurate. Integration tests can verify that example code in documentation actually runs.

Velocity: Automated publishing removes manual deployment steps. Documentation changes can go live within minutes of merge rather than requiring a separate publication process.

Maintainability: Version control makes it possible to understand why documentation changed, roll back changes, and maintain multiple documentation versions for different product releases.

The docs-as-code approach is now standard at most major technology companies and is rapidly spreading to other technical domains.

DITA and Structured Authoring

For large-scale documentation — enterprise software, regulated industries, multi-product organizations — the Darwin Information Typing Architecture (DITA) provides a structured approach to technical content.

DITA is an XML-based standard for technical documentation that enforces topic-based authoring: all content is written as small, independent topics that can be assembled into different outputs (user guides, reference manuals, help systems) by specifying which topics belong in which deliverable.

The advantages of structured authoring:

• Content can be reused across multiple documents
• Translation costs are reduced because changed content can be identified precisely
• Consistent structure is enforced across large writer teams
• Content can be published to multiple output formats from a single source

The disadvantages:

• DITA has significant overhead for small teams and simple products
• The structured authoring approach constrains writing in ways that can make documentation feel formulaic
• The toolchain (DITA-OT and authoring tools like Oxygen XML) is complex

For most documentation contexts — especially software documentation for technical audiences — docs-as-code with Markdown is more practical. DITA is primarily relevant in enterprise software documentation, aerospace, medical devices, and similar regulated-industry contexts.

What Technical Writers Do: A Day in the Work

A technical writer's daily work is more varied than many people expect.

Information Gathering

The most consistently difficult aspect of technical writing is extracting accurate information from subject matter experts. Engineers build systems and understand them deeply; they often struggle to explain them to non-experts, are unaware of which aspects are confusing to outsiders, and are under pressure that makes documentation a lower priority than shipping.

Technical writers develop specific skills for knowledge extraction:

• Structured interviews with prepared questions
• Shadowing engineers or following along with development
• Reading existing documentation, code, and internal materials to arrive prepared
• Building relationships that make engineers willing to invest time

Writing, Editing, and Reviewing

The actual writing process for technical documentation emphasizes different skills than other writing:

Accuracy over style. A beautiful sentence that misleads a user is worse than an awkward sentence that is correct. Every procedural step must be tested and verified.

User-centered structure. The organization serves the user's tasks and questions, not the product's architecture or the writer's logical preferences.

Minimalism. Technical documentation should contain what users need, not everything the writer knows. Excessive documentation is itself a usability problem — users have to wade through more material to find what they need.

Consistent terminology. Calling the same thing by different names creates confusion. Technical writers maintain terminology glossaries and style guides to enforce consistency.

Working with Developers and Engineers

The relationship between technical writers and developers is one of the defining dynamics of the field. It ranges from deeply collaborative — writers and engineers pair on documentation the way developers pair on code — to transactional, where writers are handed completed products and expected to document them.

The best technical writing teams are integrated early in the product development process. A technical writer reviewing design specifications can catch documentation problems before they are built. A writer who understands why a feature works the way it does writes better documentation than one who is handed it finished.

Technical Writing Tools

The tools technical writers use depend heavily on the context:

Documentation platforms: GitBook, ReadMe, Confluence, Notion, Notion, BookStack — platforms purpose-built for documentation management with collaboration features.

Static site generators: MkDocs, Docusaurus, Sphinx, Hugo, Jekyll — convert Markdown or reStructuredText files into polished documentation websites, typically used in docs-as-code workflows.

API documentation tools: Swagger/OpenAPI for REST APIs, with tools like Redoc and Stoplight for rendering interactive documentation from API specifications.

Help authoring tools: MadCap Flare, Adobe RoboHelp, HelpNDoc — traditional tools for producing help files and user guides, particularly in enterprise contexts.

Diagramming tools: Mermaid (embeds diagrams in Markdown), Lucidchart, Diagrams.net — for creating architectural diagrams, flow charts, and process diagrams.

Style checkers: Vale — a documentation-specific linter that enforces style guide rules automatically on Markdown text.

Version control: Git is essential in any docs-as-code workflow; GitHub, GitLab, and Bitbucket are the major hosting platforms.

The Skills That Matter in Technical Writing

Technical writing requires a specific combination of skills that does not fit neatly into either "writing" or "technical" alone.

Core Writing Skills

Clarity: The ability to express complex ideas in plain, direct language without sacrificing accuracy. This is harder than it sounds — expert knowledge tends to collapse distinctions and rely on terminology that is not shared.

Structure: The ability to organize information so users can find what they need. Good documentation architecture is largely invisible — users find what they need without noticing the organization.

Editing: Technical writers write, but they also edit — their own work, subject matter experts' drafts, and peer writers' content. The ability to distinguish good from mediocre at the sentence and document level.

User empathy: Accurate mental models of who will read the documentation, what they know, what they are trying to accomplish, and what will confuse them. This often requires directly observing users interacting with documentation.

Technical Skills

Domain knowledge: Technical writers in software must understand software concepts well enough to write about them accurately. They do not need to be able to write production code, but they need to understand how code works, what APIs are, how authentication systems function, and similar foundational concepts.

Tool proficiency: Git, Markdown, the relevant documentation platform, and the developer tools (terminal, API clients, SDKs) used to test documented procedures.

Reading code: The ability to read and understand existing code well enough to document what it does and verify that documentation examples work.

Career Paths and Salary

Technical writing is a recognized profession with a defined career path, professional certification (Society for Technical Communication's CTC and CTP certifications), and growing demand, particularly in technology.

Career Progression

Junior technical writer / associate technical writer: Typically 0-3 years experience. Writes documentation under mentorship. Works on well-scoped documentation projects with clear subject matter expert support.

Technical writer: 3-7 years experience. Works independently on full documentation projects. Develops subject matter expertise in specific technical domains.

Senior technical writer: 7+ years experience. Owns documentation strategy for products or product areas. Mentors junior writers. May manage documentation system architecture.

Staff / Principal technical writer / Documentation engineer: Technical specialist with deep expertise. Works on systemic documentation infrastructure, tooling, or particularly complex technical subjects.

Documentation manager / Head of documentation: Manages teams of technical writers. Owns documentation strategy, tools, and quality standards across an organization.

Salary Ranges (U.S., 2024)

Role	Salary Range
Junior technical writer	$50,000 - $75,000
Technical writer	$70,000 - $100,000
Senior technical writer	$90,000 - $130,000
Staff / Principal	$120,000 - $160,000
Documentation manager	$120,000 - $170,000

Salaries at large technology companies (Google, Microsoft, Meta, Amazon) are significantly higher, with total compensation including equity often 40-60% above base salary. Remote work is widely available in the field.

How to Enter the Field

There is no single path into technical writing. Technical writers come from engineering backgrounds, journalism, English, linguistics, science communication, instructional design, and many other disciplines.

What typically distinguishes competitive candidates:

• A portfolio of documentation samples — technical accuracy and clarity matter more than institutional credentials
• Demonstrated technical competence — understanding of software development concepts, familiarity with APIs and developer tools
• Experience with docs-as-code tools — Git, Markdown, at least one static site generator
• Writing clarity — the ability to write about a technical subject clearly for a specific audience

Many technical writers start by contributing to open-source documentation. Projects maintained by the Linux Foundation, Mozilla, Python, and similar organizations welcome documentation contributions and provide a visible portfolio of real work.

Why Good Technical Documentation Matters

The gap between a product that works and a product that gets adopted is often documentation.

Research consistently finds that developers, for example, rate documentation as the most important factor in their choice of third-party tools and APIs — ahead of price, support quality, and feature set. Poor documentation creates support costs: users who cannot find answers in documentation contact support, generating tickets that would not exist with better documentation.

In enterprise software, documentation quality directly affects sales. Procurement teams evaluate documentation during vendor selection. Poor documentation signals poor product quality and poor support.

In regulated industries — medical devices, aerospace, pharmaceuticals — technical documentation is a legal requirement. The consequences of inadequate or inaccurate documentation extend from regulatory penalties to liability.

Technical writing is often treated as a finishing step, something done after the product is built. The evidence argues for treating it as part of the product itself — because for users, the documentation they interact with is a core part of their experience of the product.

Summary

• Technical writing translates specialized knowledge into documentation that enables users to act: user guides, API docs, tutorials, reference, SOPs, white papers
• The Divio documentation framework divides docs into four types by purpose: Tutorials (learning through doing), How-to guides (accomplishing specific tasks), Reference (accurate system description), and Explanation (understanding concepts)
• Docs-as-code uses plain text (Markdown), version control (Git), and automated pipelines — enabling collaboration with developers and keeping documentation close to the code it describes
• DITA is a structured XML authoring standard for large-scale enterprise documentation
• Technical writers gather information from SMEs, write and test documentation, manage docs in version-controlled platforms, and contribute to documentation strategy
• Key skills: writing clarity, information architecture, domain knowledge, Git/Markdown, user empathy
• Salaries range from ~$55,000 (junior) to $160,000+ (staff/principal) with much higher total compensation at large tech companies
• Good documentation is product quality — not a finishing step

Frequently Asked Questions

What is technical writing?

Technical writing is the practice of creating documentation that communicates complex, specialized information to audiences who need to understand or use it. This includes user guides, API documentation, installation instructions, white papers, standard operating procedures, and release notes. Technical writers translate information from subject matter experts into documents that are accurate, clear, and organized for their intended audience's needs and context.

What is the Divio documentation framework?

The Divio documentation system, developed by Daniele Procida, divides documentation into four types by purpose: Tutorials (learning-oriented, designed to teach beginners through doing), How-to guides (goal-oriented, designed to help users accomplish specific tasks), Reference (information-oriented, designed to describe the system accurately), and Explanation (understanding-oriented, designed to illuminate concepts). Each type serves a different user need and should be written differently.

What is docs-as-code?

Docs-as-code is a technical documentation philosophy and practice where documentation is written in plain text formats (typically Markdown or reStructuredText), stored in version control (typically Git), reviewed through pull request workflows, and built through automated pipelines — the same tools and processes used for software code. This approach improves collaboration between technical writers and developers, enables documentation to track code changes closely, and allows documentation to be published automatically.

What do technical writers actually do day-to-day?

Technical writers typically interview subject matter experts (engineers, product managers, support staff) to extract accurate information; write, edit, and structure documentation; test the procedures they describe to verify accuracy; work with UX designers on interface text (microcopy); maintain and update existing documentation as products change; manage documentation in content management systems or version-controlled repositories; and contribute to documentation strategy decisions. In developer-facing roles, they often write sample code and maintain API reference documentation.

What is the salary range for technical writers?

In the United States, technical writer salaries (2024 data from Bureau of Labor Statistics and industry surveys) range from approximately \(55,000 for entry-level roles to \)130,000+ for senior technical writers at technology companies, with median salary around \(79,000. Senior documentation engineers and docs managers at large technology companies can earn \)150,000-$200,000+ including equity. The field requires no specific degree, though a background in writing, computer science, engineering, or a technical domain is typical.