Docs insights

Relay reads the titles and headings of your docs from your repository. It compares them with what people search for, so you can see where the docs fall short.

1. Set the docs pathsCopy Anchor Link

You need a connected repository. See GitHub publishing.

1. Open Project settings > Integrations.
2. In the GitHub publishing card, find Docs and select Set docs paths.
3. Enter the docs path on your site, such as /docs/.
4. Enter the docs directory in your repository, such as content/docs.
5. Select Save, then Index now.

2. The docs indexCopy Anchor Link

Relay reads the Markdown and MDX files in the docs directory on the base branch, with read-only access.

• Relay stores the file path, the page URL, the title, the headings with their anchors and the word count. It does not store the text.
• The title comes from the title field in the front matter, or from the first # heading.
• A file such as content/docs/guides/index.mdx becomes the page /docs/guides.
• Relay reads up to 500 files and 10 MB, in path order.
• A file larger than 32 KB keeps its path, but Relay does not read its title or headings.
• The Docs index job in Automation runs once a day. It reads only the files that changed, up to 200 files a run.
• When you change the docs paths, Relay deletes the index and builds it again.

3. Find docs gapsCopy Anchor Link

On the Opportunities page, select Find docs gaps. The run is free. It reads the last 28 days of Search Console and GA4 data and the docs index, and it runs once a day at most.

• The search gap and stale page checks need GA4. The search gap check also needs site search in GA4 enhanced measurement.
• The docs median at a position needs 3 docs pages there with 100 or more impressions each.
• Relay reads the last change date for the 50 most-viewed docs pages only, with one GitHub request each.
• The run says which checks it skipped and why.

Product changes and launches also move docs searches and traffic. Treat each item as a question to check, not as proof.

4. Edit the docsCopy Anchor Link

Approve a docs opportunity, then select Edit the docs in its publishing section. Choose a file from the docs index and one change:

• Insert a section after a heading. The new section goes at the end of the chosen heading's section. Start it with a heading at the same level.
• Add an item to the list under a heading. Relay uses the list's own bullet or number style.
• Replace one paragraph. Paste the current paragraph exactly. Relay replaces top-level paragraphs only.

Relay then checks the change:

• The front matter and every JSX block, import, expression and HTML block stay byte-identical. Relay refuses an edit inside a JSX block.
• The new text must be Markdown only, without JSX, imports or HTML.
• The heading or paragraph must appear exactly once at the top level of the file.

The proposal shows the exact Markdown and the rendered text, before and after. Nothing is written to GitHub until you approve the pull request.

5. Draft with AICopy Anchor Link

In Edit the docs, you can ask Relay for a draft. A draft uses usage credits.

• Relay writes only from these sources: the docs file, up to two related docs pages, the CHANGELOG.md file and an OpenAPI file (openapi.yaml, openapi.yml or openapi.json) at the repository root, and the facts you type in.
• Relay reads the first 32 KB of each file.
• When the text needs a fact that the sources do not give, the draft has a visible placeholder, such as [Owner: add the exact command].
• Code, commands, options and API fields come only from the sources. Relay refuses a draft with any other code.
• Every fact in the draft must quote a source exactly, and every number must appear in a source.
• You cannot prepare the change until you fill every placeholder.

Read every fact before you approve the pull request.

6. Measure the resultCopy Anchor Link

After the docs change deploys, Relay tracks it as an experiment. The experiment page shows Search Console clicks and position for the page, and a Docs search result card.

• Select Measure searches. Relay counts GA4 site searches for the item's search term in the 4 weeks before the deployment and the 4 weeks after it. Terms with the same words count together.
• The result is ready 30 days after the deployment.
• Relay shows fewer searches or more searches only when each window has 50 or more searches and the change is 25% or more. Otherwise the result is inconclusive.
• Fewer searches can mean that the docs now answer the question. Product changes, launches and seasons also move these numbers, so a result is not proof.

7. Support topics from GitHub IssuesCopy Anchor Link

Relay can group your GitHub issues into topics and show the topics that the docs do not answer. This is off on a server until its owner sets RELAY_SUPPORT_TOPICS=on. Turn it on only when your privacy policy covers ticket text.

1. In the Docs section of the GitHub publishing card, select Use GitHub Issues.
2. Give the GitHub App, or the repository token, read access to Issues.
3. The Support topics job in Automation runs once a day. Read tickets now runs it at once. Both use a few credits for embeddings.

What Relay does with the tickets:

• It reads the title and the first message of the issues opened in the last 90 days. It skips pull requests.
• It removes email addresses, phone numbers, links with tokens and the requester's GitHub name before any other step.
• It groups similar issues into topics, names each topic by its most common words, and finds the docs page that matches the topic best.
• It stores only the topic name, the counts for the last 28 days and the 28 days before, the matching docs page, and up to 3 redacted issue titles of 200 characters or less. It does not store the ticket text.
• A topic with 10 or more issues in 28 days becomes a Support topic opportunity when you select Find docs gaps.

To stop, select Disconnect and delete topics. Relay deletes every topic and excerpt.