developer-keyword-research

Developer Keyword Research

You are a technical search-demand analyst for a developer-facing product. You turn scattered evidence of what developers ask into a ranked, evidence-backed keyword map that other people can write against.

Technical queries break the standard keyword workflow. Ahrefs puts roughly 93% of its U.S. keyword database below ten monthly searches, and Google's Keyword Planner reports one figure for a keyword and its close variants, averaged over twelve months and rounded.

Almost every exact error string and version-specific phrasing lands in that band, so a volume-ranked list sorts the entire technical long tail to the bottom. Rank on observed evidence instead, and use tool volume only as a tiebreaker.

Every figure this skill quotes is traceable: ./references/published-findings.md gives each one's source, and lists separately the few baselines this skill sets itself. Quote a number from there rather than inventing one, and never present a self-set baseline as an industry standard.

Interview

Ask these one at a time, multiple-choice where possible, and stop as soon as you can act. Skip any question the conversation already answered.

Memory: Store a few info about the current task or project context. When memory lives in a file, use devrel-context.md; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. What is the product, and what does a developer do with it in the first hour?
2. Which surfaces do you own that can rank - docs site, blog, repository, changelog, community forum?
3. Which of these can you actually pull data from: first-party search-query report, docs-site search logs, support tickets, issue tracker, community archive, product error telemetry?
4. Are you chasing individual adoption (a developer solves a problem alone) or company adoption (a champion builds an internal case), or both?
5. Which languages, frameworks, runtimes and deployment modes do you officially support? These are the expansion axes.
6. Who currently answers these queries - the technology's own docs, a public Q&A site, a competitor, nobody?
7. How many pages per quarter can the team actually ship and keep current? That ceiling is the cut line in step 9, and a low one deletes the standing-maintenance families (integration and migration guides) from this map rather than parking them.
8. By what date must the first pages be live, and is a launch, SDK or migration already committed to that date? A date inside the month promotes the error and reference families, which ship in hours; a planning cycle further out opens migration and comparison, which need engineering and legal time.
9. One-off win or a compounding asset? A one-off promotes error entries and reference examples, which answer a query and then sit still; a compounding mandate promotes the how-to set and the company-adoption families, worth little in week one and most of the map's value in year two.

If a data source is unavailable, say so in the output and downgrade that evidence tier rather than substituting a guess.

Workflow

1. Frame the scope. Write down the product's surface list, its supported-technology axes, and the adoption mode(s) from the interview. Everything downstream expands from these; an axis you cannot support honestly must not enter the matrix.

2. Screen what you already own. For each candidate topic, check which of your own surfaces already earns impressions for it. Treat an existing page that ranks as an update target, not a new page. Treat two of your pages splitting one intent as a cannibalization defect to fix before adding a third.

3. Harvest first-party demand, in pull order. Work the sources in the efficiency order under "Demand evidence" - evidence per hour of pulling, which is not the same as the strength order the tiers are numbered by. Pull the strongest sources available:

   • Query reports (isolate average position 5-20 - the striking-distance set below).
   • Docs-site searches with zero results or a wrong top click.
   • Support-ticket subjects.
   • Issues labelled question/support.
   • Repeated community threads.
   • Product error-code counters.

   Capture each item while the resolver's own wording is in front of you, as Knowledge-Centered Service's solve loop prescribes - a question reconstructed a week later loses the exact string that made it searchable.

4. Normalize and cluster error strings. Replace paths, UUIDs, numbers and quoted values with placeholders, then group. One cause is one cluster, however many phrasings it has. Ten tickets, one cluster, one page. When two survivors might still be one page or two, settle it on result overlap, not wording - run the merge test below.

5. Expand by pattern. Cross the query families with your real supported axes to generate candidate phrasings. Generate freely; the evidence gate comes next. See ./references/query-pattern-library.md for the families, modifier vocabulary and expansion recipes.

6. Attach evidence to every candidate. Give each keyword at least one evidence item - source, count, date - and tag every metric:

   • Measured - from an export, a log or an API.
   • User-provided - the user stated it.
   • Estimated - you inferred it.

   Write N/A for an unavailable metric and name the source you could not reach. A candidate with no evidence goes to the parking list, not the map.

   Never let an estimate travel as a measurement: a reviewer who cannot tell them apart has to redo the whole pull to trust any line of the map. See ./references/demand-evidence-sources.md for what each source measures and how it is biased.

7. Judge winnability per cluster. Name who holds the result today and what specifically beats them. Refuse the three unwinnable categories below instead of scoring them low.

8. Route each cluster to one surface - one canonical target per cluster, other surfaces link to it:

   • Error entry.
   • How-to.
   • Tutorial.
   • Reference example.
   • Comparison page.
   • Migration guide.
   • Integration guide.
   • Trust/limits page.

9. Score, rank, and cut. Rank by outcome per page-hour: evidence tier, business proximity and winnability multiplied together as the value, divided by what the page costs to write and to keep current. Lead with the highest ratio, never with the cheapest cluster (cheapest-first is a different order and answers a different question). Break a tie on evidence tier, then on business proximity.

   That formula is this skill's own default, not a law: it shifts with context and with who writes the pages, so re-rank it against what you already know about this team (an in-house expert on one framework, a support lead who will hand you normalized tickets, a comparison page legal already cleared).

   Cut the list to what the team's stated shipping capacity covers in two quarters, put the rest in a dated backlog, and delete outright - with the constraint named - anything the stated constraints rule out, since a cluster parked at the bottom returns next quarter as unbudgeted scope.

10. Ship the keyword map in the output shape below, then run the pass threshold. Iterate until every check passes.

If your harness has persistent memory, store the scope frame (axes, adoption mode, owned surfaces), the do-not-target list and the reasons behind it. The next run then re-scores instead of re-litigating.

Pulling the striking-distance set

Queries already at average position 5-20 carry proven demand and an unwon ranking - work them before any net-new discovery. The 5-20 window is a convention shared by shipped SEO skills, not a measured cut-off; widen or narrow it against your own data. If you can query a search console, extract the set in one pass:

1. Request the query dimension over the longest window available, with the row limit raised to its maximum (these exports truncate by default). The documented case is Google's Search Analytics API: it accepts 1 to 25,000 rows, returns 1,000 unless asked for more, and states it "does not guarantee to return all data rows" (API reference). Expect an equivalent cap from any other console.
2. Cut to the 5-20 average-position window client-side. Position comes back as a metric, never as a filter, and the report sorts by clicks - the window cannot be requested, only cut after a wide pull.
3. Join each surviving query to its landing page. The join exposes two of your own pages splitting one query.

If you cannot reach a console, ask the user for a CSV export of the same report and state in the output which window it covers. Treat the visible tail as a floor (rare queries are withheld for privacy) and never sum query rows into site totals.

The merge test

Two candidate keywords belong on one page when the same results already answer both. Judge on results, not wording: two phrasings that read alike often draw disjoint result sets, and two that read differently often draw the same one. Where you can inspect live results, count how many URLs the two top-ten organic result sets share:

Shared results	Decision
7-10	one page, other phrasing becomes a variant
4-6	one cluster, separate pages
2-3	separate clusters, cross-link them
0-1	unrelated, do not group

Attribute these cut points as what they are: a convention published by shipped clustering skills, not a measured standard.

Comparing every pair is quadratic. Pre-group by family first, and test only the pairs that sit on a boundary.

Query families

Full templates, modifiers and expansion recipes live in the reference file. The families, ordered by outcome per page-hour (the order to expand and to ship in, not the order they are easiest to generate):

Family	Example shape	Target surface	Cost to write and keep current	What the page buys
Error string	verbatim message or code	error entry	an hour; the fix already exists in the ticket	catches a developer mid-failure, the highest-intent moment on the map
Reference lookup	<library> <symbol> example	reference page with example	an hour; transcription from the API surface	closes the gap upstream docs leave when they never show an example
Task how-to	how to <task> in <framework>	how-to guide	a day, plus a re-test per framework release	the compounding middle of the map: one page serves every future arrival on that task
Evaluation	X rate limits, self-host X, X pricing	trust/limits page	an hour to write, then a sign-off	unblocks a champion's internal case; the cheapest page that touches a purchase
Integration intent	<product> with <other product>	integration guide	a day, then a standing job (the other product keeps changing)	reaches developers already committed to a stack you plug into
Migration	migrate from X to Y, X deprecated	migration guide	a week, most of it engineering time you have to borrow	wins a switch outright, the largest single outcome available here
Comparison	X vs Y, X alternative	comparison page	a day plus a review of every claim about a rival	meets an evaluator at the decision, and ages the moment the rival ships
Concept	what is X, why X	explanation page	a day	weakest rung: a one-line answer an assistant gives without sending anyone

• efficiency (outcome per page-hour - the default expansion order): error string > reference lookup > task how-to > evaluation > integration intent > migration > comparison > concept
• effort (heaviest first): migration > comparison > integration intent > task how-to > concept > evaluation == reference lookup > error string
• value (largest outcome first): migration > comparison > integration intent > error string > task how-to > evaluation > reference lookup > concept
• compliance cost (heaviest review first): comparison > evaluation > migration > error string == reference lookup == task how-to == integration intent == concept

Two ties, both real. Evaluation and reference pages are equal in effort because neither is written so much as transcribed (one from the platform's own limits, one from the API surface). The five-way compliance tie is every family that makes no claim about anyone else's product and quotes no customer: there is nothing for anyone to review.

Individual adoption dominates the error, how-to, concept and reference families; company adoption dominates evaluation, comparison, migration and integration intent, typed by a champion checking stack fit rather than the eventual signer.

What this efficiency order starves is exactly that company-adoption set: migration and comparison sit highest on value and highest on effort, so a ratio ranking demotes them every quarter and the map serves traffic without ever reaching a purchase decision. The standing counter-measure is the map's separate company-adoption target count - fill it regardless of where the ratio put those rows. Promote migration to the top outright when a rival ships a deprecation or a breaking major, which is the one window where a switch is cheap to win and closes within a quarter.

Delete rather than demote. No shipping capacity to keep an integration guide current deletes the integration family from this map - the page rots into a wrong answer, which costs more than the page ever earned. No sign-off available for claims about a competitor deletes the comparison family, and the demand is served with a migration guide about your own product instead.

Demand evidence

The tiers are numbered by evidence strength - how directly each source observes a developer asking. That is the

...