How to Create an Integration Guide for Third-Party Tools

Integrations are where software ecosystems come alive — and where they break. Users do not use your product in isolation. They connect it to their CRM, their email platform, their project management tool, their analytics suite. When those connections work seamlessly, your product becomes indispensable. When they fail, your product takes the blame — even when the other tool caused the problem.

An integration guide is the documentation that bridges two products, two sets of terminology, and two support teams. Writing one well is a unique challenge because you are documenting the interaction between systems, not just one system in isolation.

What Is an Integration Guide?

An integration guide is documentation that explains how to connect your software with a third-party tool, how data flows between them, and how to troubleshoot issues that arise in the connection. It covers authentication, configuration, data mapping, and ongoing maintenance of the integration.

It differs from API documentation, which describes the technical interface. An integration guide is user-facing — it tells a non-developer admin or power user how to set up and manage a specific connection without writing code.

Key Insight: Integrations are a top-three purchasing factor for B2B software buyers. Yet research shows that 45% of users who attempt to set up an integration abandon the process due to unclear documentation. Every failed integration setup is a potential churn risk.

When Do You Need an Integration Guide?

You need one for every integration you officially support. The bar is that simple. If your product connects with another tool and you list that connection as a feature, you need documentation for it.

Prioritize guides for:

Most popular integrations — The ones the majority of your users connect.
Most complex integrations — The ones that generate the most support tickets.
Revenue-critical integrations — The ones that enterprise customers require before purchasing.
New integrations — Fresh launches need documentation on day one, not three months later.

Structuring an Integration Guide

Every integration guide should cover the full lifecycle: connecting, configuring, using, troubleshooting, and disconnecting.

1. Integration Overview

Start with the big picture before any technical steps:

What the integration does — In one or two sentences, describe the value. "The Salesforce integration syncs your customer data between [Product] and Salesforce, ensuring both teams work from the same source of truth."
What data flows and in which direction — Specify whether the sync is one-way or bidirectional, and which data types are included.
Who needs it — Which roles or teams benefit from this integration.
What you need before starting — Prerequisites from both your product and the third-party tool.

2. Prerequisites

List everything needed to begin. Be specific about both sides:

In your product:

Required plan or subscription tier.
Required user role (Admin, Owner).
Specific features that must be enabled.

In the third-party tool:

Required plan or subscription tier.
Required user role or admin access.
API access enabled (if applicable).
Specific settings or modules that must be active.

Pro Tip: Link directly to the third-party tool's documentation for prerequisites that involve their platform. Do not try to document their product in full — just provide enough context so users know what to look for.

3. Connection Setup

Walk through the connection process step by step. Most integrations follow one of these authentication patterns:

OAuth flow — User clicks Connect, is redirected to the third-party tool to authorize, then redirected back.
API key — User generates an API key in the third-party tool and pastes it into your product.
Webhook URL — User copies a webhook URL from your product and configures it in the third-party tool.

For each pattern, document:

Every screen the user sees during the process, with screenshots.
Exactly which permissions to grant during authorization.
What a successful connection looks like.
What to do if the connection fails.

4. Configuration

After connecting, most integrations require configuration:

Field mapping — Which fields in your product correspond to which fields in the third-party tool.
Sync frequency — How often data syncs (real-time, hourly, daily) and whether this is configurable.
Sync direction — Whether data flows from your product to the third-party tool, the reverse, or both.
Filters — Which records are included in the sync (all records, specific segments, records meeting criteria).
Conflict resolution — What happens when the same record is modified in both systems between syncs.

Key Insight: Field mapping is the step where most integration setups stall. Users need a complete mapping table showing every field pair, including any data transformations that occur during sync.

5. Usage and Data Flow

Once configured, explain how the integration works in daily use:

Automatic behaviors — What happens without user intervention (e.g., "New contacts in Salesforce automatically appear in [Product] within 15 minutes").
Manual triggers — Actions users can take to force a sync or push specific records.
Sync status — Where to check whether the integration is running, when the last sync occurred, and whether there are errors.
Data flow diagram — A visual showing how data moves between the two systems. This diagram is worth more than a thousand words of description.

6. Troubleshooting

Integration troubleshooting is complex because problems can originate in either system or in the connection between them.

Structure your troubleshooting section around symptoms:

Integration shows as disconnected — Steps to reconnect and common causes of disconnection.
Data is not syncing — How to diagnose whether the issue is on your side or the third party's side.
Duplicate records appearing — How to identify and resolve duplicate creation.
Field data is incorrect after sync — How to check field mapping and data transformation rules.
Sync is slow or delayed — Rate limits, queue backlogs, and how to check sync status.

For each symptom, provide:

Possible causes — Listed from most likely to least likely.
Diagnostic steps — How to narrow down the cause.
Resolution — How to fix it.
When to contact support — Clear criteria for when the user should escalate.

Common Mistake: Only documenting the "happy path" and ignoring error states. Integrations fail regularly due to expired tokens, changed permissions, API rate limits, and data format changes. Every common failure needs documentation.

7. Disconnecting the Integration

Document how to cleanly remove the integration:

What happens to synced data when you disconnect.
Whether disconnecting is reversible.
Steps to revoke permissions in the third-party tool.
How to clean up residual data if needed.

Writing for Two Audiences Simultaneously

Integration guides have a unique challenge: you are writing about two products for users who may know one well and the other barely at all.

Do not assume familiarity with either product. The user setting up a Salesforce integration might be a Salesforce expert who just started using your product, or a power user of your product who has never touched Salesforce. Write for both.

Use clear labels. When showing screenshots, always label which product you are showing. "In Salesforce:" and "In [Your Product]:" before each screenshot or instruction set.

Translate terminology. If your product calls something a "workspace" and the other tool calls the equivalent a "project," state this explicitly. A terminology translation table is invaluable.

Show both sides of the setup. Many integrations require configuration in both tools. Show the complete process, alternating between the two interfaces as needed.

Pro Tip: Create a "Terminology Map" table at the top of the guide that translates between the two products' vocabularies. Users reference this constantly.

Visual Documentation for Integrations

Integration guides are among the most screenshot-heavy documentation types. You are showing interfaces from two different products, data flow diagrams, and configuration screens.

Screenshot Strategy

Capture both product interfaces. For every step that involves the third-party tool, capture their interface too.
Label every screenshot. Include the product name and the specific screen name in the caption.
Show the OAuth flow end-to-end. Capture the authorization prompt, permission selection, and success confirmation.
Capture error messages. Show what common errors look like in both products.

Data Flow Diagrams

Create a visual diagram showing:

Which system is the source for each data type.
The direction of data flow (one-way arrows or bidirectional arrows).
Any transformation that occurs during transit.
Sync frequency for each data type.

ScreenGuide is especially helpful for integration guides because you need to capture and annotate screens from multiple applications. Walk through the setup in both tools, capture everything with consistent annotations, and organize the visuals into a coherent narrative.

Rate Limits and Performance

Document the performance characteristics of the integration:

API rate limits — How many requests per minute/hour both your product and the third-party tool allow.
Sync volume limits — Maximum records per sync cycle.
Impact on performance — Whether the integration affects application performance during sync.
Bulk operation guidance — How to handle initial sync of large datasets versus ongoing incremental syncs.

Common Mistake: Ignoring rate limits in documentation. Users import 100,000 records, hit the third-party tool's API rate limit, and the sync fails halfway through. Document the limits and recommend batch sizes.

Versioning and Compatibility

Both your product and the third-party tool release updates independently. Document:

Supported versions — Which versions of both products the integration supports.
Breaking changes — Any known version upgrades that affect the integration.
Update process — Whether integration updates happen automatically or require manual action.

Key Insight: Integration breakage after a third-party API update is one of the most common causes of integration support tickets. Proactively documenting version compatibility and monitoring for changes reduces these incidents.

Maintaining Integration Guides

Integration documentation requires more maintenance than most documentation types because you are tracking changes in two products.

Monitor the third-party tool's changelog. Subscribe to their developer blog, release notes, and API changelog. Any change to their API or OAuth flow may affect your guide.
Test quarterly. Walk through the integration setup from scratch every quarter to catch drift.
Track integration support tickets. Tag tickets by integration and review them monthly to identify new issues for the troubleshooting section.
Update screenshots from both products. When either product changes their interface, update the relevant screenshots. ScreenGuide makes this manageable by letting you recapture specific screens without rebuilding the entire guide.

Putting It Together

TL;DR

An integration guide covers the full lifecycle — connecting, configuring, using, troubleshooting, and disconnecting two software products.

Document prerequisites from both your product and the third-party tool, including plan requirements and permissions.

Provide a complete field mapping table and data flow diagram showing what syncs, in which direction, and how often.

Write for two audiences — users who know your product and users who know the third-party tool — without assuming familiarity with either.

Document every common failure mode with symptoms, diagnostic steps, and resolutions.

Monitor the third-party tool's changelog and test the integration setup quarterly to catch documentation drift.

Integrations are the connective tissue of modern software workflows. Your integration guide is what makes those connections reliable — not just on day one, but every day after.

Ready to create better documentation?

ScreenGuide turns screenshots into step-by-step guides with AI. Try it free — no account required.

Try ScreenGuide Free