Define the decision behind the integration search
Someone searching for a product integration may be asking several different things: whether a connection exists, whether it supports a particular action, or how to repair an existing setup. Begin with the decision your page serves. A discovery page can summarize fit and prerequisites, then link to a setup guide and troubleshooting reference. It does not need to hide every task inside one promotional page.
For a fictional project tool, the relevant task might be creating a task from an incoming support request. That is more specific than saying the product integrates with a support platform. Identify the trigger, action, data, and person responsible. The use-case page guide helps define the job; the integration page adds the connection-specific evidence a buyer needs.
State what kind of connection is actually available
Distinguish a native integration maintained by the product team from a third-party automation, an API-based custom implementation, or a manual import. All can be useful, but they involve different work and support responsibilities. Explain the current availability and avoid describing a possible future API workflow as an existing one-click integration.
Verify requirements on both sides. A connection may need an administrator, a particular plan, an external service account, or permissions that the person reading the page cannot grant. Record the sources and date checked. If a third party provides the connector, name that dependency and explain where its current limits and support terms can be confirmed.
Show the data contract in plain language
Explain the trigger, action, direction, fields transferred, timing, and important exclusions. A one-way task creation workflow does not necessarily synchronize later updates. A connection that copies a title may omit attachments or comments. Those details change whether the integration fits the reader’s work, so place them near the main explanation.
Use a small verified example with synthetic data. Show the source record, the resulting record, and any mapping the owner must configure. Avoid exposing real customer tickets, personal information, or access credentials in screenshots. The example should make the actual behavior inspectable without implying broader coverage than the connection supports.
| Question | Example answer to verify | Why the answer matters |
|---|---|---|
| What starts the workflow? | A request enters a selected queue | Defines which records are affected |
| What is created? | A task with mapped title and priority | Shows the actual output |
| Do later edits synchronize? | No; creation is one-way in this example | Prevents assumptions about ongoing sync |
| Who can configure it? | An owner with the required access | Identifies the person needed for setup |
| What happens after a failure? | Confirm the actual retry and notification behavior | Makes recovery a verified requirement |
Demonstrate the first successful run
A setup explanation should move from prerequisites to connection, field mapping, a test action, and a visible success check. Include the expected result so a reader can distinguish completion from merely saving settings. Keep the steps aligned with the current interface and identify any preparation that must happen in the connected service.
GitHub’s documentation guidance recommends defining the audience, core purpose, and suitable content type before writing. Apply that distinction here: a short overview answers whether the connection fits, a how-to completes setup, and troubleshooting handles failures. Link those resources at the point where the reader needs them instead of stretching a marketing description into an incomplete manual.
Explain failure and ownership before the first incident
Investigate what the real integration does when authentication expires, a required field is missing, a request is repeated, or one service is unavailable. State only verified behavior. If the team has not checked retries or duplicate handling, treat that as a product or documentation task rather than filling the gap with a reassuring sentence.
Give the reader a safe way to identify the failed step and find relevant help. Explain who maintains each part of the connection and which logs or status indicators are available without exposing sensitive details. A buyer may decide that a supported manual workflow is preferable to a fragile automated one. A useful page makes that tradeoff visible.
Choose a distinct page only when there is a distinct answer
An individual integration page earns its place when the connection has enough verified detail to help someone evaluate or use it. A directory of supported tools can link to those pages. Avoid publishing dozens of tool-name pages that offer the same generic paragraph or describe connections that nobody has implemented. The page should answer a real query with product-specific substance.
Use the integration name naturally in the title, heading, and explanation. Link to the relevant use case, setup instructions, and plan conditions. If pricing determines access, connect the page to an accurate pricing explanation. Keep the next step consistent with the actual availability, whether that is self-serve setup or a conversation about requirements.
Maintain the connection as a product dependency
Assign an owner and review triggers such as a changed permission flow, new plan condition, updated field mapping, or partner API change. Keep current screenshots and a record of the last verified test. A page can remain searchable long after the connection stops behaving as described, so maintenance is part of the usefulness of the page.
Review the questions readers still ask and where the first test fails. A visit that ends in a working connection is a different outcome from a page view or a click on a connect button. Use those observations to improve both the documentation and the integration. Search visibility introduces the workflow; accurate guidance helps someone complete it.