The job market for documentation has quietly split into three roles that share a title and don't share a job description. A company posts for a "technical writer," interviews a candidate who can do narrative tutorials in their sleep, and hires them into a codebase where the OpenAPI spec is half-finished, the static site generator is four majors behind, and the retrieval layer is whatever the framework shipped with. Six months later nobody is happy. The writer is exhausted. The engineering team is frustrated that the docs still look broken. The VP who approved the req is wondering why a senior hire produced so little.

The mismatch is not about talent. It is about the job description. "Technical writer" as a title has fractured into three distinct roles with different skills, different deliverables, and different reporting lines. Hiring for the wrong one is the single most expensive mistake we see in developer-experience orgs. This post draws the lines, gives you a rubric sharp enough to use in your next hiring-committee meeting, and names the case where you should hire none of them.

The three roles, clearly named#

Before the rubric, the vocabulary. If your hiring committee cannot tell these three apart in one sentence each, you are not ready to open the req.

The technical writer#

A technical writer is a narrative craftsperson. Their raw material is a messy, accurate explanation from an engineer who has never been interviewed before, and their output is prose a non-expert can follow without losing any of the precision the engineer cared about.

Core skills in 2026: structured writing, information architecture, interviewing, editing, working command of a style guide, basic Markdown and Git, and enough fluency with the product to ask the second question. The best of them write with opinion and cut with discipline.

Typical deliverables: conceptual overviews, tutorials, onboarding flows, quickstarts, release notes that developers actually read, and the kind of long-form explanatory page that takes three interviews and four drafts to get right.

Weakness, stated plainly: they are not the right person to rebuild your publishing pipeline. They can live inside a good one and make it shine. They cannot construct one.

The documentation engineer#

A documentation engineer treats docs as a product, with a build process, a release process, and instrumentation. They write code and they write prose, and they are unusual in the market because most people who can do both prefer to do one.

Core skills in 2026: a working software-engineering background (TypeScript or Python is typical), deep familiarity with static site generators and docs frameworks (Docusaurus, Mintlify, Nextra, Fumadocs, Astro Starlight, the Diátaxis-native tools that showed up in the last two years), OpenAPI and AsyncAPI tooling, docs CI, link and snippet testing, versioning strategy, analytics instrumentation, and increasingly the retrieval layer that feeds LLM-based assistants. They ship pipelines and prose on top of them.

Typical deliverables: the docs site itself, OpenAPI-to-reference pipelines, automated sample-code validation, migration tooling across versions, a retrieval stack tuned for both human search and agent ingestion, and the CI that keeps the whole thing honest on every PR.

Weakness, stated plainly: the narrative craft of a long tutorial is not where they shine, and most are not the right person to conduct an extended interview with a founding engineer who has never explained their system to an outsider.

The developer advocate#

A developer advocate is the public face of the developer-facing product. They write code-as-content, not pages-as-content. Their audience is external, their feedback loop is the community, and their measure of success is adoption and signal rather than coverage and clarity.

Core skills in 2026: public speaking, demo building, working sample applications that survive contact with real developers, conference and community presence, social writing, and the strategic empathy to carry external signal back into product decisions.

Typical deliverables: conference talks, reference applications, ecosystem blog posts, demo videos, community engagement, and structured product feedback from the field.

Weakness, stated plainly: they are not the canonical source of internal knowledge, and they often move on to the next ecosystem before the docs reach a stable state. Treating a DevRel hire as your docs owner is a staffing error that hides for a year and then hurts.

Most companies hiring a "technical writer" want one of these three and do not yet know which.

A hiring rubric#

Four questions, answered in order. Do not skip ahead.

Does your publishing stack work?#

Open the docs site on a Tuesday morning and look at it like a first-time user. Is the OpenAPI rendered in a way a developer would trust? Does search return the right page in the top three results? Is versioning handled or faked? Do snippets run in CI? Can a PR change a page and preview it in under a minute?

If the honest answer is no, your first hire is a documentation engineer. A traditional writer joining a broken stack will spend six months firefighting tooling they were not hired to own, and they will produce a fraction of the content you expected. Fix the substrate first.

Do you have a steady flow of engineering content that needs to be shaped?#

A steady flow means a roadmap that ships features monthly, new concepts to explain, SDKs with real surface area, and a product surface growing faster than any single engineer can document in passing. If yes, and the stack is already solid, hire a technical writer. The writer's precondition is that the pipeline works. The engineer has already paid that bill.

If the flow is lumpy or the product is still moving under you every quarter, a full-time writer will be underused. Revisit in two quarters.

Do you need a voice in the developer community?#

If adoption depends on talks, demos, and presence in the ecosystems where your users already live, hire a developer advocate. This is a separate role with separate success metrics, and it does not replace either of the above. Companies that try to fuse advocacy with internal docs ownership get neither done well.

Do you have fewer than ten customer-facing docs pages?#

If yes, hire none of the three. Write the docs yourself, as the founder or the tech lead. It will not scale, and you will dislike doing it, but the cost of the wrong hire at this stage exceeds the cost of another quarter of founder-authored pages. A premature docs hire at pre-PMF is one of the most common ways to waste a year of headcount.

Two refinements worth holding in mind while you answer these. First, seniority beats headcount. One senior documentation engineer is worth two mid-level writers if the stack is the bottleneck, and one senior writer is worth two juniors if the prose is. Second, reporting line matters. Documentation engineers belong in engineering, with a dotted line to product or DX. Writers belong wherever the content pipeline lives, which is usually product or DX. Advocates belong in marketing or DevRel, never in docs. Put the role in the wrong org and the best candidate in the market will still underperform.

The most common mistake#

The most expensive hiring mistake we see, by a wide margin: a growth-stage company concludes "the docs need work," writes a job description for a senior technical writer, points the new hire at a broken publishing stack and an under-specified OpenAPI, and expects polished content within the quarter.

The writer cannot deliver. Not because they are not talented, but because the work in front of them is not writing work. It is pipeline work dressed up as a content problem. They have three options, all bad. They can burn out trying to do both jobs. They can pivot into docs engineering on the job, picking up the skill gap in public and shipping slower than either a writer or an engineer would have. Or they can leave inside a year, at which point you post the same req and hire the same mismatch.

The pattern repeats because the symptoms look identical from the outside. Docs that feel broken to a developer could be a writing problem, a tooling problem, a retrieval problem, or a content-strategy problem, and the surface-level complaint ("our docs are bad") does not distinguish them. Leadership pattern-matches "docs" to "writer," posts the req, and the role arrives pre-scoped to fail.

The fix is mechanical. Before you write a job description, audit the stack. Walk the rubric above in a room with your head of engineering and your head of product. If the publishing substrate is the bottleneck, the first hire is a documentation engineer, full stop. The writer comes second, into a pipeline that lets them do the job they were hired for. Reversed, you waste two years and a senior salary. Done in order, the writer you hire in year two will outproduce the one you would have hired in year one by a factor that makes the sequencing obvious in hindsight.

One more tell: if your interview loop for a "technical writer" keeps asking candidates about CI, OpenAPI tooling, or search infrastructure, you are not hiring a writer. You are hiring a documentation engineer and calling them a writer to justify the salary band. Fix the title, fix the band, and hire the person the work actually needs.

What to do when you need all three#

You will need all three eventually. The order is almost always engineer, then writer, then advocate. The engineer makes the pipeline capable of supporting a writer. The writer produces the canonical content that makes an advocate credible in the field. The advocate carries that work outward and brings signal back.

Beyond three hires, the role separation matters less and the team dynamics matter more. You start needing a head of docs or a head of DX who can hold the three functions in tension, a content lead who can mentor juniors, and an editorial standard that survives handoffs. That is a different post.

When to hire nobody#

Two cases deserve a full-time hire less than a calendar invite suggests.

The first is pre-PMF with a small user base. Write the docs yourself, keep the backlog narrow, and defer the hire until the product stops moving underneath you every sprint. A docs hire before PMF is optimizing for a shape the product has not taken yet.

The second is a defined, bounded project with a deadline. One-off rebuilds, retrieval audits, OpenAPI overhauls, migrations from a legacy stack, or a six-week push to get a launch-ready docs surface are agency-shaped work. Hires pay off over years. Agencies pay off in quarters. Match the tool to the timeline. If the work has a start date and an end date, a full-time hire will either be underused after it ships or pulled into maintenance work they were overqualified for.

We run an agency, so read that recommendation with appropriate skepticism. The honest version: a hire is the right answer when the work is continuous and the surface keeps growing. A contract is the right answer when the work is bounded and the bar is high. Neither is universally better.

The takeaway#

A docs team is three roles in a trench coat. The first hire is almost never the one the job description is asking for, because the job description was written from the symptom rather than the diagnosis. Walk the rubric, name the role, and post the right listing. The cost of getting this wrong is a year of wasted headcount and a docs surface that does not improve. The cost of getting it right is a team that compounds, quarter over quarter, into the kind of documentation your developers stop complaining about.