> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synscribe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Research Documentation Questions Before Writing

> Research documentation questions from support, sales, product, search, and community evidence, then assign each question one owner page.

Research documentation questions before writing by building a **Question Map**: one row for every
meaningful user question, backed by customer, product, support, search, or community evidence, with
one canonical page assigned to own the answer.

If you arrived from the
[documentation page optimization lesson](/theory/documentation-site/optimize-documentation-pages-for-seo-geo),
use this process to replace its `RESEARCH PLACEHOLDER` fields with evidence. The result is not a
keyword dump. It is a prioritized set of real questions, their audience language and scope, the page
shape each answer requires, and one stable owner URL for every question.

This changes the planning conversation from “What content should we publish?” to:

* What is the user trying to do or decide?
* What words do they actually use?
* What proof shows the question is real?
* Which page should give the complete answer?
* What is missing or duplicated today?

## Why documentation research needs more than a keyword list

Documentation demand behaves differently from broad marketing demand:

* Queries are often long, technical, and version-specific.
* Exact error messages may have low reported volume but very high intent.
* Support questions and failed integrations may never appear in a commercial keyword tool.
* Agents often reformulate a task into several subquestions.
* Internal product terminology may not match the words a new user knows.
* The valuable outcome is usually task completion, not page views.

Use search volume as a tiebreaker where it is reliable. Do not use it as the gate that decides whether
a required error, security, migration, or implementation answer exists.

## Build a Question Map for documentation demand

Create a sheet or database with these columns:

| Field                    | What it means                                                                |
| ------------------------ | ---------------------------------------------------------------------------- |
| `id`                     | Stable question identifier                                                   |
| `question`               | The normalized question in user language                                     |
| `also_asked_as`          | Real variants and related wording                                            |
| `source`                 | Support, sales, community, logs, search, competitor, analytics, release      |
| `source_evidence`        | Ticket IDs, transcript links, query export, error string, or URL             |
| `frequency`              | Count or qualitative recurrence; never invent it                             |
| `audience`               | Evaluator, implementer, operator, troubleshooter, approver                   |
| `intent_stage`           | Find, research, shortlist, act, recover                                      |
| `archetype`              | Quickstart, how-to, integration, decision, reference, error, troubleshooting |
| `product/version/locale` | Scope that changes the answer                                                |
| `who_answers_today`      | Current first-party or third-party winner, if known                          |
| `owning_page`            | Exactly one canonical page that should answer it                             |
| `page_status`            | Keep, rewrite, merge, split, create, redirect, retire                        |
| `target_title`           | Task-shaped title in market language                                         |
| `business_risk`          | Cost if the answer is absent or wrong                                        |
| `priority`               | Now, next, later                                                             |
| `owner` / `due`          | Accountable person and target date                                           |

Do not leave duplicate owner pages unresolved. Supporting pages may link to the answer, but one URL
must be the clearest primary result.

## Step 1: define the documentation research scope

Before collecting questions, write down:

* current company, product, and feature names;
* former names that users may still search;
* audiences and their level of technical knowledge;
* supported regions, languages, products, frameworks, and API versions;
* the actions and decisions that matter commercially;
* high-risk actions where an incorrect answer can move money, expose data, break production, or
  create compliance risk.

This prevents a mixed corpus from answering the right question for the wrong product or version.

## Step 2: mine documentation questions from evidence

Use at least four source types. One must be direct customer evidence such as support or community
questions. Otherwise the map tends to become an internal feature inventory disguised as research.

### Mine questions from support tickets and implementation escalations

This is usually the best source because it records a real goal, real wording, and the point where the
current product or docs failed.

Extract:

* the question before support translated it into internal terminology;
* exact error text and payload shape;
* environment, product, version, region, and integration;
* what the customer had already tried;
* the answer or workaround that resolved the issue;
* whether the same root cause appeared in other tickets.

Cluster by root cause, not surface phrasing. Five tickets that say “webhook failed,” “signature
invalid,” and “401 callback” may belong to one owner page—or to separate pages if the diagnosis and
fix differ.

### Mine questions from sales-engineering and solution-design calls

These reveal questions that block selection before implementation:

* “Can this run in our cloud?”
* “Which Typeform API should we use?”
* “Can the Calendly API show user availability?”
* “How do Dropbox uploads work for files over 150 MiB?”
* “What data leaves our region?”

Capture both the question and the evidence the prospect needed to accept the answer.

### Mine questions from communities and off-property discussions

Review public forums, GitHub issues, Stack Overflow, Reddit, Discord/Slack communities, videos, and
independent tutorials where relevant. These show the vocabulary users choose when your navigation is
not prompting them.

Record when a third-party page answers a product question better than the official docs. That is both
a content gap and a possible corroboration opportunity.

### Mine exact questions from product and API error strings

Export production and support-visible errors, then rank them by affected users, severity, and support
cost. Exact error strings are efficient content targets because they are distinctive and usually map
to an immediate need.

For every important error, capture:

* exact code and message;
* operation and product area;
* likely causes;
* a test that separates the causes;
* safe retry behavior;
* minimal fix;
* current owner page, if any.

### Mine questions from internal site search and analytics

Start with:

* zero-result searches;
* searches followed by rapid reformulation;
* searches that lead to support contact;
* high-traffic pages with low completion or high backtracking;
* exits from quickstart, auth, error, and pricing/limits pages.

Traffic alone does not prove the page helps. Join it to a meaningful action where possible.

### Validate documentation questions in search results

Use autocomplete, related searches, “People also ask,” and the actual result set for:

* brand + task;
* category + task;
* narrow subcategory + task;
* exact error;
* product + integration;
* product/category comparison;
* security, pricing, deployment, limits, and migration questions.

Record the result type that wins. If the result is a tutorial, write a better task page. If it is a
comparison article, the gap may require both a first-party decision page and off-site inclusion. If no
useful result exists, direct customer evidence can still justify the page.

### Find answer gaps in competitor and exemplar documentation

Use competitor navigation, sitemaps, public API contracts, and `llms.txt` files to find missing
question families and useful page shapes. Copy neither wording nor unsupported claims. The useful
questions are:

* Which task has a dedicated URL there but not here?
* Which integration or error is self-contained there?
* Which decision can a new user make there without contacting sales?
* Which page is easier to retrieve and why?

Use this command to turn a competitor's `llms.txt` into a quick page-title inventory:

```bash theme={null}
curl -fsSL https://competitor.example/llms.txt \
  | rg -o '^- \[[^]]+\]' \
  | sed 's/^- \[//;s/\]$//'
```

Do not copy the output into your backlog blindly. Compare it with customer evidence and mark which
question family is genuinely missing from your site.

### Use models to expand questions without inventing demand

After collecting real evidence, ask several current answer engines or models to generate questions
for each audience and task. Use the output to find blind spots, not as proof of demand.

Run this prompt against two or three current models with web search enabled:

```text theme={null}
You are a [role] integrating [product], which [one-sentence product description], for the first time.

List the 40 questions you would need answered before choosing the product and completing the first
working integration. Write each question exactly as you would type it into a search engine or ask a
coding agent.

Group the questions into:
- evaluation and selection;
- setup and authentication;
- first working integration;
- common tasks and integrations;
- limits and edge cases;
- errors and debugging;
- production readiness and migration.

Be specific. "How do I authenticate?" is too broad. "Where do I get a sandbox API key and which
request header carries it?" is specific enough.
```

Then run the gap test against the current routing index:

```text theme={null}
Here is the current documentation index:

[paste llms.txt]

For each question in the list:
1. say whether the titles and descriptions identify one page that should answer it;
2. name that page;
3. mark the answer as clear, ambiguous, or missing;
4. for every ambiguous or missing answer, propose the one page that should own it.

Do not treat a product or feature name as proof that the user's task is answered.
```

Model output is a hypothesis backlog. A row becomes evidence only after it is connected to a real
ticket, call, query, error, usage pattern, or observed result gap.

Then test whether the model can answer the top questions from the current site. Record:

* whether the product or page surfaced;
* the URL opened or cited;
* whether the answer was correct and current;
* unsupported or hallucinated claims;
* what source would have prevented the mistake.

### Mine upcoming questions from the changelog and product roadmap

Every release, migration, renamed product, new integration, changed limit, and deprecation can create
or invalidate questions. Add them to the map before or with the release, not months later.

## Step 3: normalize documentation questions into user language

Raw evidence is noisy. Rewrite each item as a single task or decision while preserving the original
phrasing in `also_asked_as`.

Good normalized questions:

* “How do I create a form programmatically with the Typeform API?”
* “How do I display Calendly availability in a React calendar?”
* “How do I list more than 100 Airtable records?”
* “When should I use a Dropbox upload session instead of `/files/upload`?”

Weak normalized questions:

* “Webhooks” — topic, not a question.
* “Content-upload endpoints” — internal category, no user goal.
* “Integrations” — too broad.
* “Everything about errors” — several different intents.

Prefer a verb, one task, and the qualifier that changes the answer. Keep exact error strings exact.

Use these rewrites as a pattern:

| Rewrite rule                              | Raw wording       | Normalized task or question                                                        |
| ----------------------------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| Lead with the user's action               | `Create form`     | `How do I create a form programmatically with the Typeform API?`                   |
| Translate internal jargon                 | `List records`    | `How do I retrieve and paginate records from an Airtable table?`                   |
| Preserve the user's noun                  | `Availability`    | `How do I display a user's Calendly availability in a calendar?`                   |
| Split combined jobs                       | `Contacts`        | `How do I create an Intercom contact?` plus `How do I update an Intercom contact?` |
| Add the qualifier that changes the answer | `Upload a file`   | `How do I upload a file under 150 MiB?` and `How do I upload a larger file?`       |
| Keep exact errors exact                   | `upload conflict` | `How do I fix a Dropbox path-conflict error during an upload?`                     |

## Step 4: translate audience language into product terminology

Create a living mapping between market language and product language.

| Users may say                          | Product calls it                      | Writing rule                                                      |
| -------------------------------------- | ------------------------------------- | ----------------------------------------------------------------- |
| Create a form from code                | Typeform Create API                   | Lead with the form outcome, then name the API                     |
| Download submitted answers             | Typeform Responses API                | Say what the reader retrieves before relying on `responses`       |
| Receive booking changes automatically  | Calendly webhook subscription         | Name scheduled and canceled events before the subscription object |
| Show open meeting times                | Availability schedules and busy times | State that both endpoint results must be combined                 |
| Get rows from a table                  | Airtable `List records`               | Introduce records after the table-retrieval task                  |
| Continue after the first 100 rows      | Airtable offset pagination            | Explain the next-page outcome before relying on `offset`          |
| Upload a small file                    | Dropbox `/files/upload`               | State the 150 MiB limit and content-upload request shape          |
| Upload a large file                    | Dropbox upload session                | Lead with the size-dependent choice                               |
| Add a lead or user to support software | Intercom contact                      | Define the contact role before using the product object name      |
| Choose the API region                  | Intercom regional server              | Name the data-hosting region and resulting base URL               |

Do not erase product terminology. It is needed for correct use and existing users. Introduce it after
the phrase a new user already understands.

## Step 5: classify the documentation page archetype

| Archetype               | The user needs                         | Typical owner page                           |
| ----------------------- | -------------------------------------- | -------------------------------------------- |
| Quickstart              | First verified success                 | One short, opinionated path                  |
| How-to                  | Complete a known task                  | Procedure with prerequisites and recovery    |
| Integration/permutation | Make product A work with product B     | Full setup plus working use                  |
| Concept/decision        | Understand or choose between paths     | Decision table plus default                  |
| Reference               | Look up exact contract detail          | Complete structured specification            |
| Error                   | Fix one exact code/message             | Cause, diagnosis, fix, retry guidance        |
| Troubleshooting         | Diagnose a symptom with several causes | Symptom-shaped sections and branching checks |

Do not force every question into an FAQ. A question that requires steps deserves a how-to. An exact
error deserves its own stable answer. A major choice deserves a decision page.

## Step 6: assign each documentation question one owner URL

For every row, choose one action:

* **Keep:** one page already answers it well.
* **Rewrite:** the right page exists but uses the wrong framing or lacks completeness.
* **Merge:** two pages compete for the same intent.
* **Split:** one page mixes tasks whose procedures or audiences differ.
* **Create:** no page owns the question.
* **Redirect:** an old path should preserve links to the new owner.
* **Retire:** the question or product path is obsolete, with a stated replacement where relevant.

A page can support many related phrasings. It should not try to own several unrelated jobs.

## Step 7: validate the highest-priority documentation questions

Validate at least the top 40 questions—or the complete set if the product is smaller.

For each priority question:

1. Run a neutral, logged search from the target market.
2. Record the top useful sources and the answer format they use.
3. Check whether a current first-party page appears and whether it deserves to.
4. Ask a fixed set of current answer engines or agents.
5. Record mention, citation/opened URL, factual answer, date/model, and current-vs-deprecated use.
6. Where the task is executable, run the generated result in a sandbox or contract test.

This is a baseline, not a one-time verdict. Search and model results vary by date, geography, product,
and prompt.

Classify what kind of query you are trying to win. The class changes both the page and the
distribution work:

| Query type  | Example                           | Practical implication                                                              |
| ----------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| Brand       | `Typeform create form API`        | The first-party site should own it; repair identity or routing if it does not      |
| Task        | `create a form programmatically`  | Compete with a complete task page and evidence of successful use                   |
| Subcategory | `form API with conditional logic` | Often narrower and more winnable; publish the exact capability and working example |
| Category    | `online form API`                 | Docs alone may not win; pair first-party evidence with off-site corroboration      |
| Error       | `Typeform IMAGE_NOT_FOUND`        | Publish the exact-error owner page; no competitor can authoritatively replace it   |

## Step 8: prioritize the documentation backlog

Use evidence, user value, and risk rather than volume alone. A practical order is:

1. Dangerous or high-frequency errors and deprecations.
2. Existing pages that can win through a title, opening, and completeness rewrite.
3. The first-success quickstart.
4. High-frequency support how-tos.
5. High-value integrations and product permutations.
6. Decision pages that unblock evaluation or route users to the right path.
7. Category pages and off-site corroboration.
8. Lower-frequency reference supplements.

For each item, consider:

* **User value:** does it unblock a real task or decision?
* **Evidence strength:** how many reliable sources show demand?
* **Business/risk impact:** what happens if the answer is absent or wrong?
* **Current gap:** is the answer missing, wrong, buried, or duplicated?
* **Effort and dependency:** can it ship now, or does product truth need clarification?

Do not turn this into a fake precision score. A documented compliance risk can outrank a high-volume
informational query by policy.

## Worked Question Map seeds for Typeform and Calendly

These are starting hypotheses. Validate them against support, product usage, and search data before
treating them as the final roadmap.

### Typeform Question Map seed

| Question                                                | Archetype/type   | Owning page                                           | Current state                                                 | Target title                                                      | Action                                                                  |
| ------------------------------------------------------- | ---------------- | ----------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| How do I create a form programmatically?                | Quickstart/task  | `/developers/create/reference/create-form/`           | Complete schema, generic identity, no minimal success path    | `Create a Form Programmatically with the Typeform API`            | Add endpoint-first opening, minimal request, response, and next task    |
| Which Typeform API or SDK should I use?                 | Decision/task    | `/developers/get-started/`                            | Products are introduced, but the page is not a decision owner | `Choose the Right Typeform API or SDK for Your Task`              | Map Create, Responses, Webhooks, and Embed to user outcomes             |
| How do I authenticate a personal script?                | How-to/task      | `/developers/get-started/personal-access-token/`      | Existing owner; verify completeness                           | `Authenticate Typeform API Requests with a Personal Access Token` | Show token creation, request, verification, and revocation              |
| How do I authenticate an app for other users?           | How-to/task      | `/developers/get-started/applications/`               | OAuth material is separated from the first request            | `Create a Typeform OAuth App and Make an Authenticated Request`   | Connect registration, scopes, callback, token, and test call            |
| How do I retrieve form responses?                       | How-to/task      | `/developers/responses/reference/retrieve-responses/` | Reference owner needs a task entry path                       | `Retrieve and Filter Responses with the Typeform API`             | Add pagination, filters, expected response, and errors                  |
| How do I receive a response as soon as it is submitted? | Integration/task | `/developers/webhooks/`                               | Broad API owner                                               | `Receive Typeform Submissions with a Webhook`                     | Show endpoint setup, payload verification, retries, and test submission |
| What does `IMAGE_NOT_FOUND` mean?                       | Error/error      | `[create exact-error owner]`                          | Mentioned inside Create form reference                        | `IMAGE_NOT_FOUND: Add an Image Before Creating a Typeform`        | Explain cause, upload prerequisite, safe retry, and related endpoint    |

### Calendly Question Map seed

| Question                                             | Archetype/type       | Owning page                                                                   | Current state                                                | Target title                                                              | Action                                                                        |
| ---------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| How do I make my first Calendly API request?         | Quickstart/task      | `/getting-started`                                                            | Useful overview, but no focused first-success path           | `Make Your First Calendly API Request`                                    | Choose one read-only call, show auth, response, and next task                 |
| How do I display a user's availability?              | How-to/task          | `/displaying-availability-of-users`                                           | Vague title, unfinished copy, no runnable code block         | `Display User Availability with Calendly's API`                           | Combine schedule and busy-time data into one tested table or calendar example |
| How do I create a webhook subscription?              | How-to/task          | `/receive-data-from-scheduled-events-in-real-time-with-webhook-subscriptions` | Good procedure; long title and awkward description           | `Create Calendly Webhook Subscriptions for Scheduled and Canceled Events` | Tighten metadata, format the request, and add verification                    |
| When should I use OAuth instead of a personal token? | Decision/task        | `/when-to-choose-between-personal-access-tokens-and-oauth`                    | Dedicated owner exists                                       | `Choose OAuth or a Personal Access Token for Calendly`                    | State the default by audience, scopes, lifecycle, and migration path          |
| How do I embed a scheduling page in my app?          | Integration/task     | `/how-to-display-the-scheduling-page-for-users-of-your-app`                   | Task page exists; verify runnable completeness               | `Embed a Calendly Scheduling Page in Your App`                            | Show one implementation, expected UI, events, and common failures             |
| How do I schedule meetings from an AI agent?         | Integration/task     | `/schedule-events-with-ai-agents`                                             | Differentiating task owner exists                            | `Schedule Calendly Meetings from an AI Agent`                             | Show tool choice, auth, availability check, booking, and confirmation         |
| Why is my availability display wrong?                | Troubleshooting/task | `[create symptom owner]`                                                      | Current article does not own time-zone and interval failures | `Fix Missing or Incorrect Calendly Availability`                          | Branch by schedule, busy time, time zone, date override, and permissions      |

## Definition of done for documentation question research

Research is ready to drive writing when:

* the Question Map contains the agreed priority set;
* at least four source types were used, including support or community evidence;
* source evidence is traceable rather than summarized from memory;
* internal jargon has a market-language translation;
* every question has one owner page and a page action;
* the top set has a recorded search and agent baseline;
* dangerous errors, deprecations, and selection claims have subject-matter owners;
* priorities and due dates are assigned.

The map remains a product asset. Update it from new support issues, site-search gaps, releases, and
evaluation failures every month; revalidate the top set at least quarterly.