Docs as Marketing
for Developer Tools.
The docs site is the highest-converting top-of-funnel asset a DevTools company owns. Technical writers and PMMs are working on the same surface from two directions — IA on one side, positioning on the other. The boundary where each ends and the other begins is the difference between docs that activate and docs that don't.
By Daria Dovzhikova · Updated May 2026
TL;DR
- The docs site outperforms every other top-of-funnel asset for a developer-first company. Treating it as engineering output rather than as a marketing surface is the most common reason DevTools companies underperform on top-of-funnel.
- Tech writers own the IA (Diátaxis quadrants). PMMs own the positioning the IA expresses (concepts, comparisons, integration pages). The interface is the positioning statement — one sentence that both sides translate into their native artifacts.
- Measure docs the way marketing measures a funnel. Quickstart completion rate, activation per docs page, top exit pages, top in-site search queries. The instrumentation is identical to a landing-page funnel; nearly nobody applies it to docs.
Why docs is the highest-leverage marketing surface
A developer evaluating a tool follows a recognizable path: a Google search lands them on the docs, a quickstart runs in their terminal, the working code becomes the artifact they remember, and the docs site becomes the surface they return to. They do not bounce through a marketing landing page on the way. The docs site is the marketing site for the audience that matters.
That fact is rarely controversial when stated; it is consistently underacted on. Most DevTools companies budget docs as engineering output, scope it as a technical writer's deliverable, and measure it (when they measure it at all) as pages shipped. The companies that outperform treat docs as a marketing surface with engineering accountability — they fund it, instrument it, iterate on it, and assign joint ownership across the writer and the PMM.
This page maps the boundary between those two roles. The Write the Docs community is the canonical reference for the writing side; the developer-first PMM page covers the PMM side. The interesting work happens where the two surfaces meet.
Five phases of treating docs as a marketing surface
Each phase produces a concrete artifact or measurement, not an abstract orientation. A DevTools company that completes all five operates a docs surface that is meaningfully more productive than the median.
Phase 01: Recognize docs as a marketing surface
The docs site is the highest-traffic, highest-intent, highest-converting top-of-funnel asset most DevTools companies own. Underinvesting because it sits in the engineering org chart is the most common cause of soft top-of-funnel. The fix is structural: name docs as a marketing surface even when the writer reports into engineering, give the PMM a seat in the docs roadmap, and budget for content there the way you budget for blog content.
Phase 02: Structure the IA with Diátaxis
Four quadrants — Tutorials, How-to guides, Reference, Explanation. Each serves a distinct reader intent. Tutorials are the activation funnel; How-tos are the conversion artifacts; Reference is the SEO long tail; Explanation is the positioning surface. A docs site that mixes the four into a single navigation hierarchy without naming the intent always underperforms a site that names them explicitly. The framework is forty years old in its first form and increasingly the lingua franca of the field.
Phase 03: Quickstart as the activation funnel
The single highest-leverage docs page is the quickstart. A working quickstart that completes in under five minutes is the single biggest predictor of whether a docs visitor will become an activated user. The PMM and the writer should review the quickstart weekly the way an e-commerce team reviews a checkout flow — same physics, same measurement discipline. Latency, friction, ambiguous error messages each cost measurable activation.
Phase 04: Concepts and comparisons as the positioning surface
The Explanation quadrant is where positioning lives in docs. A concepts page that names the technical mental model honestly (and names the alternative mental models the audience may be carrying in from a competitor) does positioning work that no marketing landing page can do. Comparison pages and migration guides sit here too — these are read by the buyer evaluating the technical trade-offs, not by the casual visitor, and they are also the artifacts that show up in serious peer reference conversations.
Phase 05: Measure docs the way marketing measures funnels
Activation per docs page. Time-to-quickstart-complete. Top exit pages. Top search queries within the docs site. Top referring pages from Google. The instrumentation is the same instrumentation that a marketing team would apply to a landing page; the difference is that nearly nobody applies it to docs because docs are nominally engineering output. The first DevTools company that does the measurement well finds a list of two or three pages where small fixes produce outsized activation gains.
The tech writer's lens vs the DevTools PMM's lens
The two roles look at the same docs site and read different things. The writer reads structure, accuracy, completeness, voice. The PMM reads positioning, conversion, audience match, competitive differentiation. Neither lens is more correct; the docs site that performs is the one where both lenses have been applied.
| Axis | Tech writer lens | DevTools PMM lens |
|---|---|---|
| Primary frame | Diátaxis quadrants, IA, voice consistency | Positioning statement expressed through structure |
| Owned artifacts | Tutorials, How-to guides, Reference, Explanation | Concepts pages, comparison pages, integration pages, landing |
| Quality metric | Accuracy, completeness, readability, currency | Activation rate, conversion to free tier, search-to-quickstart |
| Failure mode | Stale docs, broken examples, missing reference entries | Soft positioning, weak comparison, missing landing flow |
| Boundary point | Tone and structure of every page | Which pages exist and what they each have to claim |
The shared spine is the positioning statement and the IA. The two lenses fail catastrophically when one tries to do the other's work — the docs that activate live where both lenses have been applied with discipline.
By the numbers
Three references that frame the field. Each one is short enough to read in an hour and pays back permanently for the docs investment.
Daniele Procida's four-quadrant documentation framework — Tutorials, How-to guides, Reference, Explanation. The lingua franca for organizing a developer-tool docs site. Reading it once is a one-hour investment with permanent dividends.
Diátaxis · 2024→The community of practice for technical writing. Conference talks, the Slack, and the published guides are the closest thing the field has to a canonical reference. Most credible DevTools technical writers are at least docs-curious participants there.
Write the Docs · 2024→Procida's original framing essay introducing Diátaxis. Useful as the source text when introducing the framework to a team that has not yet adopted it; the diagrams alone usually settle the docs-IA argument inside engineering.
Diátaxis (Procida) · 2024→Diátaxis in DevTools-specific terms
The four quadrants of Daniele Procida's Diátaxis framework map onto a DevTools docs site almost cleanly. Naming them out loud forces every page on the site to be answerable to a single reader intent — the reason most generalist documentation reads as muddy is that individual pages try to serve more than one quadrant at once.
Tutorials (learning-oriented).The quickstart and the "build your first integration" flow. The reader does not yet know whether the product fits their problem. The success measure is completion. This quadrant doubles as the activation funnel — every PMM should consider these pages funnel pages.
How-to guides (task-oriented)."How do I authenticate?" "How do I deploy this to a Kubernetes cluster?" The reader has a specific task and a specific environment. The success measure is task completion without bouncing back to search. This quadrant doubles as the conversion artifact — most developers convert to paid after completing one or two how-to flows.
Reference (information-oriented).API method signatures, configuration options, error code catalogs. The reader knows exactly what they are looking for. The success measure is "found it in under fifteen seconds." This quadrant doubles as the SEO long tail — most of the docs site's organic search traffic lands here.
Explanation (understanding-oriented).Concept pages, architecture overviews, "why does this work this way" essays. The reader is trying to build a mental model. The success measure is the reader being able to make a decision they could not have made without reading. This quadrant doubles as the positioning surface — every honest comparison and every conceptual differentiation lives here.
The interesting effect once a docs site is structured this way: every new page has an unambiguous home. Stale pages become identifiable because they fail their quadrant's test. New contributors (engineering, support, PMM) know which kind of page they are writing. The IA stops being a permanent debate.
SEO inside docs without breaking the docs
The docs site naturally ranks for high-intent queries (product name, error messages, API method names). The PMM's contribution to docs SEO is not to chase those keywords harder; it is to make sure the adjacent queries the audience actually types are answered by a page that exists.
Integration pages."Product X with Kubernetes," "Product X with Terraform," "Product X with GitHub Actions." These are high-intent queries with low competition; an honest one-page integration guide ranks. The PMM identifies the integrations worth ranking for; the writer produces the page with accurate, current code.
Concept pages."What is observability," "What is a service mesh," "What is dynamic logging" — the conceptual queries the audience runs before they have committed to a vendor. A docs concept page that answers the question honestly (and treats the reader as a peer, not a lead) wins these queries and converts at a meaningful rate.
Comparison and migration pages."Migrating from Y to X." The audience exists; the queries are real; the page has to be written from an honest engineering perspective rather than a marketing one. The DevTools companies that get this right (Vercel, Supabase, Hugging Face) all share the same property: the migration guide is written by someone who has done the migration, not by someone who has read the competitor's docs.
The two anti-patterns are well known and worth naming explicitly. Keyword stuffing the reference pages destroys their primary function (lookup) and produces no durable SEO gain. Comparison pages written as marketing copy are sniffed out instantly by the developer audience and damage brand trust permanently. Both behaviors trade short-term ranking for long-term audience erosion, which is exactly the wrong trade for a developer-first company.
Common docs-as-marketing mistakes
- Treating docs as engineering output. Docs is a marketing surface with engineering accountability. Underfunding because it sits in the engineering org chart is the most common cause of soft top-of-funnel.
- PMM rewriting tutorials. Breaks the technical accuracy almost every time. Stay in the positioning lane; let the writer hold the structure.
- Writer rewriting positioning. Tends to drain the differentiation. The writer is the editor of the positioning artifact, not the author.
- Mixing Diátaxis quadrants inside a single page. A page that is half tutorial and half reference serves neither audience. Pick the intent; serve it cleanly.
- No measurement. Activation rate per docs page, quickstart completion, top exits — none of this is hard to instrument. Almost no DevTools company actually does it consistently.
- Comparison pages written as marketing copy. The audience reads them as untrustworthy and the SEO benefit is short-lived. Honest engineering content wins both surfaces.
The author
Daria Dovzhikova is a fractional PMM with 12 years inside developer-first companies, including 7 years at JetBrains and senior roles at Lightrun and Odigos. Across all three companies the docs surface routinely outperformed the marketing site on top-of-funnel — and routinely got underinvested in until someone forced the conversation. This page is the version of that conversation that should not require forcing. For the wider engagement format see services or about.
The Write the Docs community is the closest thing the field has to a craft tradition for technical writing. Any DevTools PMM working seriously with a writer should at least know it exists; any writer working seriously inside DevTools probably already does.
FAQ
Is the docs site really a marketing asset or is that just PMM-speak?
It is the marketing asset. In a developer-first GTM motion, the docs site outperforms every other top-of-funnel surface a DevTools company owns — by traffic, by activation rate, and by long-tail compounding. A developer who arrives on a marketing landing page and bounces will arrive again from a Google search a week later, on the docs page that answers their actual question. The docs site is where the audience evaluates the product, where they convert into activated users, and where they later return to make purchasing decisions. Treating it as engineering output rather than as a marketing surface is the most common reason DevTools companies underperform on top-of-funnel.
Who owns the docs IA — the tech writer or the PMM?
The tech writer owns the IA. The PMM owns the positioning that the IA expresses. In healthy DevTools companies, the writer drives the structure (reference, tutorials, how-tos, conceptual explanations — the Diátaxis quadrants), and the PMM ensures that the structure surfaces the product's positioning in the right places (the landing page, the concepts section, the comparison and integration pages). The boundary breaks when one role tries to do the other's job: a PMM who rewrites tutorials usually breaks the technical accuracy, and a writer who rewrites positioning usually drains the differentiation.
Does the Diátaxis framework actually apply to a DevTools docs site?
Yes, almost without modification. Daniele Procida's framework — splitting docs into Tutorials (learning-oriented), How-to guides (task-oriented), Reference (information-oriented), and Explanation (understanding-oriented) — is the cleanest mental model the field has produced for organizing a DevTools docs site. The only DevTools-specific overlay is recognizing that the Tutorials quadrant doubles as the activation funnel and the Reference quadrant doubles as the SEO long tail. A writer who knows Diátaxis is talking the same language as a PMM who knows the activation funnel; the framework is the bridge.
How should SEO be handled inside a docs site?
Conservatively. The docs site already ranks for the high-intent queries (product name, error messages, API method names) because the audience naturally creates the search demand. The PMM's contribution is to make sure the docs surface the right adjacent queries — concept pages, integration pages, comparison pages, troubleshooting pages — without turning the docs into an SEO content mill. The two specific anti-patterns to avoid: keyword stuffing the reference pages, and writing "X vs Y" comparison pages that read as marketing rather than as honest engineering content. The DevTools audience sniffs both out instantly and the SEO benefit is short-lived; the brand cost is long.
Should a small DevTools company hire a technical writer before a PMM?
Often yes. A strong technical writer can carry the early-stage PMM workload (positioning iteration through doc structure, message testing through landing pages, activation funnel optimization through tutorial flow) better than most generalist marketers can carry the docs work. The hire order that scales is: tech writer first, fractional PMM second, internal PMM after the company has ten engineers and two products. The companies that hire a generalist marketer first and a writer later usually end up with weak docs and strong launch copy — exactly backwards for a developer-first audience.
Related reading
- Developer-first PMM — the PMM side of the docs surface.
- Developer marketing — the channel mix that the docs site sits inside.
- Developer experience — what activation actually feels like for the developer reading docs.
- Product-led growth — why docs is the activation funnel in a PLG motion.
- How to launch a developer tool — where docs sits inside the launch playbook.
Docs underperforming as a funnel?
Run a docs-as-marketing audit with someone who has done this work.
IA review against Diátaxis, positioning audit on the concepts surface, quickstart instrumentation, comparison-page review. Fractional PMM working alongside your technical writer, not around them.
See servicesReady when you are.
Discovery calls are 20 minutes. First one's on me.