Skip to content

Commit 3faa858

Browse files
tcgilberttcgilbert
authored
add template for direct destination documentation (#5070)
* add new template for direct destinations * add documentation section to direct integraiton
1 parent 9d039e6 commit 3faa858

File tree

5 files changed

+129
-12
lines changed

5 files changed

+129
-12
lines changed

‎src/partners/direct-destination.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ In the debugger panel, check the two outputs. The **Request from Segment** and t
156156
* **Request from Segment** - What Segment posted to your endpoint
157157
* **Response from destination** - How your server responded
158158

159-
### The user flow
159+
### The User Flow
160160

161161
The ultimate goal is for Partners like yourself to create and publish high quality Destinations in [the Segment Catalog](https://segment.com/catalog/). Your Segment account doubles as a sandbox account to test your destination while you are still in a private "building" state.
162162

@@ -169,3 +169,9 @@ Next you can click the "Event Tester" tab to send data to your destination. Here
169169
Now you can use the JavaScript SDK in a browser to generate real analytics events.
170170

171171
Finally you should verify the data in your service.
172+
173+
### Write documentation
174+
175+
Documentation is integral to enabling Segment's users to self-serve and onboard with your integration. Segment's documentation team will work with you during this part of the process to ensure your documentation matches the Segment style and is as instructive as possible.
176+
177+
To create your documentation, follow the instructions outlined [in this template](https://github.com/segmentio/segment-docs/blob/develop/templates/partners/direct-destination.md){:target="_blank"}

‎templates/partners/destination-new.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,7 @@
2727
## Template begins here...
2828

2929
---
30-
title: <integration_name> Destination
31-
id: <integration_id>
30+
title: [integration_name] Destination
3231
---
3332

3433
> (delete after reading) This template is meant for Actions-based destinations that do not have an existing Classic or non-Actions-based version. For Actions Destinations that are a new version of a classic destination, see the doc-template-update.md template.

‎templates/partners/destination-update.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,11 @@
2424
>
2525
> If you have any questions in the meantime, please reach out to our team at [email protected].
2626
27-
---
28-
2927
## Template begins here...
30-
28+
---
29+
title: [integration_name] Destination
3130
---
3231

33-
## title: <integration_name> Destination
3432

3533
> (delete after reading) This template is meant for Actions-based destinations that represent a new version of an existing, or Classic Segment destination. For new Actions-based destinations, see destination-new-template.md template.
3634

‎templates/partners/direct-destination.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# 💥 Segment Partner Direct Destination Documentation Template
2+
3+
> Hi Partners 👋🏼
4+
>
5+
> Welcome to Segment - glad to have you onboard! This doc serves as a guideline for your team to create best-in-class documentation alongside your amazing product.
6+
>
7+
> Here are the guidelines we want you to have in mind when writing out your documentation:
8+
>
9+
> - Be succinct and simple in your writing. Reduce text bloat where possible.
10+
> - Avoid 1st person language as it’s confusing for customers if they don’t know who wrote the docs (Segment or the Partner).
11+
> - Where pre-reading is required, hyperlink to other more generic parts of Segment’s (or your) documentation.
12+
>
13+
> - Screenshots/Images are generally discouraged unless absolutely necessary
14+
>
15+
> The below template intends to provide a standardized structure. To submit your documentation, complete the following steps:
16+
>
17+
> 1. Fork and clone the `segment-docs` repo locally
18+
> 2. Create a new branch (e.g., partner-name/destination)
19+
> 3. Create an `index.md` file in the following path `src/connections/destinations/catalog/{destination-slug}/index.md
20+
> 4. Copy the template below into your `index.md` file, and edit it to be in line with how your integration operates
21+
> 5. Add, commit, and push your code, then submit a pull request to the `segment-docs` repo
22+
>
23+
> If a section does not apply to your integration, feel free to remove. Please don’t create separate sections unless absolutely necessary. In most cases, creating a H3 (###) sub-heading under an existing section is the best option!
24+
>
25+
> If you have any questions in the meantime, please reach out to our team at [email protected].
26+
27+
## Template begins here...
28+
29+
---
30+
title: [integration_name] Destination
31+
---
32+
33+
> Include a 1-2 sentence introduction to your company and the value it provides to customers - updating the name and hyperlink. Please leave the utm string unchanged.
34+
35+
[YOURINTEGRATION](https://yourintegration.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) provides self-serve predictive analytics for growth marketers, leveraging machine learning to automate audience insights and recommendations.
36+
37+
> Update your company name and support email address.
38+
39+
This destination is maintained by YOURINTEGRATION. For any issues with the destination, [contact the YOURINTEGRATION Support team](mailto:[email protected]).
40+
41+
> Update your company name (x2) and support email address.
42+
43+
44+
## Getting Started
45+
46+
> Do not remove this line. It will auto-populate the following information for your integration:
47+
48+
{% include content/connection-modes.md %}
49+
50+
> Include clear, succinct steps including hyperlinks to where customers can locate their API Key in your app. If there is an expected delay for a customer to see data flow into your integration, please make that explicit.
51+
52+
1. From the Destinations catalog page in the Segment App, click **Add Destination**.
53+
2. Search for "YOURINTEGRATION" in the Destinations Catalog, and select the "YOURINTEGRATION" destination.
54+
3. Choose which Source should send data to the "YOURINTEGRATION" destination.
55+
4. Go to the [YOURINTEGRATION dashboard](https://YOURINTEGRATION.com/dashboard){:target="_blank"}, find and copy the "API key".
56+
5. Enter the "API Key" in the "YOURINTEGRATION" destination settings in Segment.
57+
58+
59+
> For each of the following call types (Page, Screen, Identify, Track, Group), update:
60+
> 1. Code snippet with relevant code sample including required traits or properties.
61+
> 2. Your integration name.
62+
> 3. What the corresponding call looks like within your platform (eg. Segment `page` call might be a `pageview` on your platform).
63+
> 4. It can be helpful to describe *where* data will appear (ie. Will `identify` calls appear within a Users dashboard as well as the Real-time dashboard of your platform?)
64+
> 5. Any other important information for customer to note when sending through the events.
65+
66+
## Supported methods
67+
68+
YOURINTEGRATION supports the following methods, as specified in the [Segment Spec](/docs/connections/spec).
69+
70+
### Page
71+
72+
Send [Page](/docs/connections/spec/page) calls to *ADD WHAT PAGE CALLS ARE USED FOR HERE*. For example:
73+
74+
```js
75+
analytics.page()
76+
```
77+
78+
Segment sends Page calls to YOURINTEGRATION as a `pageview`.
79+
80+
81+
### Screen
82+
83+
Send [Screen](/docs/connections/spec/screen) calls to *ADD WHAT SCREEN CALLS ARE USED FOR HERE*. For example:
84+
85+
```obj-c
86+
[[SEGAnalytics sharedAnalytics] screen:@"Home"];
87+
```
88+
89+
Segment sends Screen calls to YOURINTEGRATION as a `screenview`.
90+
91+
92+
### Identify
93+
94+
Send [Identify](/docs/connections/spec/identify) calls to *ADD WHAT IDENTIFY CALLS ARE USED FOR HERE*. For example:
95+
96+
```js
97+
analytics.identify('userId123', {
98+
email: '[email protected]'
99+
});
100+
```
101+
102+
Segment sends Identify calls to YOURINTEGRATION as an `identify` event.
103+
104+
105+
### Track
106+
107+
Send [Track](/docs/connections/spec/track) calls to *ADD WHAT Track CALLS ARE USED FOR HERE*. For example:
108+
109+
```js
110+
analytics.track('Login Button Clicked')
111+
```
112+
113+
Segment sends Track calls to YOURINTEGRATION as a `track` event.
114+
115+
---
116+
117+
> Congratulations! 🎉 You’ve finished the documentation for your Segment integration. If there’s any additional information or nuance which did not fit in the above template and that you want to share with our mutual customers, feel free to include these as a separate section for us to review. If not, you may now submit this doc to our team via your designated Slack Channel and we’ll respond with updates when we publish it and your integration!

‎templates/partners/source.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,10 @@
2424
>
2525
> If you have any questions in the meantime, please reach out to our team at [email protected].
2626
27-
---
28-
2927
## Template begins here...
30-
3128
---
32-
33-
## title: <integration_name> Source
29+
title: [integration_name] Source
30+
---
3431

3532
> (delete after reading) Include a 1-2 sentence introduction to your company and the value it provides to customers - updating the name and hyperlink. Please leave the utm string unchanged.
3633

0 commit comments

Comments
 (0)