Template · Updated
Integration setup guide template
Integration questions are common, often urgent, and hard to answer from memory, because they involve two products. A consistent structure for every integration makes them easy to write, easy to scan, and easy to keep current.
Short answer
An integration setup guide explains what the integration does, exactly what data moves in which direction and how often, how to connect it, what the customer should see afterwards, and how to disconnect or fix it. Most integration tickets come from customers assuming something syncs that doesn't, so the sync table matters most.
When to use this template
Use this template for every integration your product offers, from your most used one down. Each integration gets its own article. If an integration has several modes or a lot of settings, link separate articles for those from the setup guide rather than making it one long page. Write the guide while setting the integration up yourself in a fresh account, so every screen in both products is described as a new customer will actually see it.
What goes in it
What the integration does
One or two sentences in terms of the customer's goal: “Payments in Ledgerloop appear in your accounting tool automatically.”
What syncs, in which direction, how often
A small table. This prevents the most common misunderstandings.
Before you connect
Required plan, permissions on both sides, and anything to set up first.
How to connect
Numbered steps, including the screen in the other product.
After connecting, and how to disconnect
What the customer should see, how long the first sync takes, and what disconnecting removes or keeps.
The template
Copy it into your help center editor and replace the bracketed parts.
# Connect [Product] to [Other tool]
[One or two sentences: what this lets the customer do.]
## What syncs
| Data | Direction | How often |
|---|---|---|
| [Data] | [Product] → [Other tool] | [Instantly / hourly / daily] |
| [Data] | [Other tool] → [Product] | [Frequency] |
Not synced: [what customers often expect but doesn't sync].
## Before you connect
- [Plan or permission needed]
- [Setup in the other tool]
## Connect
1. [Step in your product]
2. [Step in the other tool]
3. [Confirm]
## After connecting
[What they'll see and when.]
## Disconnect
[Steps.] [What's kept and what's removed.]Example: Ledgerloop's accounting sync guide
# Connect Ledgerloop to your accounting software
Paid invoices in Ledgerloop appear in your accounting software automatically, so you don't enter them twice.
## What syncs
| Data | Direction | How often |
|---|---|---|
| Paid invoices | Ledgerloop → accounting | Within 15 minutes |
| Clients | Ledgerloop → accounting | When first invoiced |
| Payments recorded by hand | Ledgerloop → accounting | Within 15 minutes |
Not synced: drafts, unpaid invoices, and changes made in your accounting software.
## Connect
1. In Ledgerloop, open Settings, then Integrations, and choose your accounting tool.
2. Sign in and approve access.
3. Choose the income account for invoices and click Save.Mistakes to avoid
- Leaving out what doesn't sync, which is exactly what customers assume and then report as a bug.
- No sync frequency, so customers think it's broken when it's just not instant yet.
- Steps for your product only, skipping the screens in the other tool.
- No disconnect section, so customers don't know what they'll lose.
- One giant page covering every integration.
How to keep this article current
Integration guides drift from both sides: your product changes, and so does the other tool. usedocs proposes an edit when a merged pull request changes sync behavior, frequency, or fields the guide describes, and the scheduled check flags sync tables that no longer match the code. Questions about integrations the assistant couldn't answer become gaps with drafted articles. Changes on the other tool's side still need a person to notice.
FAQ
What's the most important part of an integration guide?
The table of what syncs, in which direction, and how often, plus what doesn't sync.
Should each integration have its own article?
Yes. Customers search for the specific tool, and separate articles are easier to keep current.
Should I document the other tool's screens?
Briefly, yes. Customers get stuck on the other side more often than you'd expect.
How do I handle integration errors?
Add a short “If syncing stops” section, or link a troubleshooting article for each common error.
How often should integration guides be checked?
When either product changes the integration, and whenever integration tickets spike.
How do I explain what doesn't sync?
Add a short “Not synced” line under the table listing what customers most often expect. It prevents more tickets than any other line in the article.
Who should write integration guides?
Whoever set the integration up most recently, reviewed by the docs owner. Fresh setup experience catches steps experts skip.