Find documentation gaps with Fluid Topics analytics
Overview
Section titled “Overview”If you publish your documentation on a Fluid Topics portal, its reader analytics show where readers look for answers and don’t find them. Connect Fluid Topics so Promptless reads those analytics, checks each signal against your documentation source, and tells you which gaps to fix first.
Promptless reads the portal’s search, view, and rating reports, such as the searches that returned no results and the topics readers rate lowest. The connection is read-only. The reports hold aggregate counts and ratings for each search term, topic, or document.
Before you start
Section titled “Before you start”- A Fluid Topics user with the
ADMINrole, to create the API key. - An admin role in your Promptless organization, to connect Fluid Topics.
- A doc collection that holds the source of the docs your portal publishes. Promptless searches it to confirm each gap.
Connect Fluid Topics
Section titled “Connect Fluid Topics”A Promptless organization admin connects one Fluid Topics portal for the whole organization. The connection uses a Fluid Topics API key with the ANALYTICS_USER or ADMIN role, because Fluid Topics accepts either for analytics web services. Give the key ANALYTICS_USER, which reads portal analytics and nothing else. ADMIN also works, but it gives the key far more access than Promptless needs.
-
In Fluid Topics, under Administration > Integration > API keys, create an API key and give it the
ANALYTICS_USERrole. Only a Fluid Topics user with theADMINrole can create API keys. -
On the Promptless Integrations page, select Connect Fluid Topics.
-
In Portal URL, enter the HTTPS address of your portal, such as
https://docs.example.com. -
In API key, paste the key.
-
Select Connect. Promptless reads one day of analytics with the key before it saves the connection. The Fluid Topics card then shows your portal and the first characters of the key.
To confirm later that the key still works, select Check access on the Fluid Topics card. To use a different key, select Disconnect Fluid Topics on the card, then connect again with the new key.
Ask Promptless for a gap analysis
Section titled “Ask Promptless for a gap analysis”Ask Promptless for a gap analysis in Slack, in Microsoft Teams, or from New Task. For example: “@Promptless find documentation gaps in our Fluid Topics analytics for the last 90 days.”
Name a date range, a locale, or a product or guide to narrow the analysis. Without a date range, Promptless uses the last 90 days for every report.
For each candidate gap, Promptless searches your doc collection for the term, its synonyms, and the product names it contains. It drops typos, terms about other products, and popular terms the docs already answer. It then classifies each remaining gap:
| Class | Meaning |
|---|---|
| Missing | No page covers the subject. |
| Findability | A page covers the subject, but readers miss it or rarely open it. Its title, headings, and metadata don’t use the readers’ term. |
| Quality | Readers find the page but rate it low. |
Promptless returns a table of gaps ranked by reader impact, and a gap that appears in several reports ranks first. Each row cites the report, the term or title, its count, and the date range. It also names the page that covers the subject, or “no page”. To fix a gap, ask Promptless to open a suggestion for it.
To run the analysis on a schedule, pair a schedule trigger with a workflow. See Example: Turn docs analytics into doc-gap suggestions.
Example
Section titled “Example”Readers of your portal at docs.example.com often search for “single sign-on” and get no results. Your docs cover the subject on a page titled “Configure SAML authentication”, and the least-viewed topics report shows that readers rarely open it.
You ask Promptless in Slack for a gap analysis of the last 90 days. Promptless finds the SAML page in your doc collection and sees that its title, headings, and metadata never use the term “single sign-on”. It reports one Findability gap with both signals, so the gap ranks near the top of the table. The row cites both reports, names the SAML page, and recommends adding “single sign-on” to its title and metadata. You reply in the thread and ask Promptless to open a suggestion for that change.
Troubleshooting
Section titled “Troubleshooting”Fluid Topics doesn’t connect
Section titled “Fluid Topics doesn’t connect”When you select Connect, Promptless reads analytics with the key. The connection saves only when that read succeeds:
- Invalid Fluid Topics API key: Fluid Topics rejected the key. Copy the key again from Administration > Integration > API keys and reconnect.
- Fluid Topics API key lacks the ANALYTICS_USER role: the key authenticates but can’t read analytics. Give the key the
ANALYTICS_USERrole in Fluid Topics, then select Connect again. - Fluid Topics host must be an https URL: Promptless connects to the portal only over HTTPS. Enter the portal URL with
https://, or with no scheme, such asdocs.example.com.
The Fluid Topics card shows Needs reconnect
Section titled “The Fluid Topics card shows Needs reconnect”Promptless checks the key regularly. The card shows Needs reconnect when Fluid Topics rejects the key, the key loses its ANALYTICS_USER or ADMIN role, or the portal stops responding. Fix the key or its role in Fluid Topics, then select Check access. If the key was deleted, disconnect Fluid Topics and connect it with a new key. See Connection health & troubleshooting.
See also
Section titled “See also”- Example: Turn docs analytics into doc-gap suggestions, for the same kind of analysis with PostHog on a schedule
- Pay down docs debt with Deep Analysis, to fix many gaps in one coordinated run