Skip to content

Commit 668a9ae

Browse files
markzegarellistayseesong
markzegarelli
and
stayseesong
authored
Add partner docs templates to non-build folder (#4145)
* Add partner docs templates to non-build folder * Apply suggestions from code review Co-authored-by: stayseesong <[email protected]> --------- Co-authored-by: stayseesong <[email protected]>
1 parent 7f70c2c commit 668a9ae

File tree

3 files changed

+242
-0
lines changed

3 files changed

+242
-0
lines changed

‎templates/partners/destination-new.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
# The end name should be similar to `Slack Destination`
3+
title: <destination_name>
4+
hide-boilerplate: true
5+
hide-dossier: true
6+
---
7+
8+
<!-- 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. -->
9+
10+
{% include content/plan-grid.md name="actions" %}
11+
12+
<!-- Include a brief description of the destination here, along with a link to your website. -->
13+
14+
<!-- This include describes the requirement of A.js 2.0 or higher for Actions compatibility, and is required if your destination has a web component. -->
15+
16+
{% include content/ajs-upgrade.md %}
17+
18+
<!-- In the section below, explain the value of this actions-based destination. If you don't have a classic version of the destination, remove this section. -->
19+
20+
## Benefits of <destination_name> (Actions)
21+
22+
<destination_name> (Actions) provides the following benefits:
23+
24+
- **Main point 1**. One or two sentences that back up the main point.
25+
- **Main point 2**. One or two sentences that back up the main point.
26+
27+
<!-- The section below explains how to enable and configure the destination. Include any configuration steps not captured below. For example, obtaining an API key from your platform and any configuration steps required to connect to the destination. -->
28+
29+
## Getting started
30+
31+
1. From the Segment web app, navigate to **Connections > Catalog** and select the **Destinations** tab within the catalog.
32+
2. Search for **<destination_name>** and select the destination.
33+
3. Click **Configure <destintation_name>**.
34+
4. Select the Source to connect to <destination_name> (Actions).
35+
36+
<!-- The line below renders a table of connection settings (if applicable), Pre-built Mappings, and available actions. -->
37+
38+
{% include components/actions-fields.html %}
39+
40+
<!--
41+
Additional Context
42+
43+
Include additional information that you think will be useful to the user here. For information that is specific to an individual mapping, please add that as a comment so that the Segment docs team can include it in the auto-generated content for that mapping.
44+
-->

‎templates/partners/destination-update.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
# The end name should be similar to `Slack (Actions) Destination`
3+
title: <destination_name>
4+
hide-boilerplate: true
5+
hide-dossier: true
6+
---
7+
8+
<!-- 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 the doc-template-new.md template -->
9+
10+
<!-- In the section above, edit the `title` field. For example, Slack (Actions) Destination -->
11+
12+
{% include content/plan-grid.md name="actions" %}
13+
14+
<!-- Include a brief description of the destination here, along with a link to your website. -->
15+
16+
<!-- In the section below, add your destination name where indicated. If you have a classic version of the destination, ensure that its documentation is linked as well. If you don't have a classic version of the destination, remove the second and third sentences. -->
17+
18+
> success ""
19+
> **Good to know**: This page is about the [Actions-framework](/docs/connections/destinations/actions/) <destination_name> Segment destination. There's also a page about the [non-Actions <destination_name> destination](/docs/connections/destinations/catalog/<destination_name>/). Both of these destinations receives data from Segment.
20+
21+
<!-- This include describes the requirement of A.js 2.0 or higher for Actions compatibility, and is required if your destination has a web component. -->
22+
23+
{% include content/ajs-upgrade.md %}
24+
25+
<!-- In the section below, explain the value of this actions-based destination over the classic version, if applicable. If you don't have a classic version of the destination, remove this section. -->
26+
27+
## Benefits of <destination_name> (Actions) vs <destination_name> Classic
28+
29+
<destination_name> (Actions) provides the following benefits over the classic <destination_name> destination:
30+
31+
- **Main point 1**. One or two sentences that back up the main point.
32+
- **Main point 2**. One or two sentences that back up the main point.
33+
34+
<!-- The section below explains how to enable and configure the destination. Include any configuration steps not captured below. For example, obtaining an API key from your platform and any configuration steps required to connect to the destination. -->
35+
36+
## Getting started
37+
38+
1. From the Segment web app, navigate to **Connections > Catalog** and select the **Destinations** tab within the catalog.
39+
2. Search for **<destination_name>** and select the destination.
40+
3. Click **Configure <destintation_name>**.
41+
4. Select the Source to connect to <destination_name> (Actions).
42+
43+
<!-- The line below renders a table of connection settings (if applicable), Pre-built Mappings, and available actions. -->
44+
45+
{% include components/actions-fields.html %}
46+
47+
<!--
48+
Additional Context
49+
50+
Include additional information that you think will be useful to the user here. For information that is specific to an individual mapping, please add that as a comment so that the Segment docs team can include it in the auto-generated content for that mapping.
51+
-->
52+
53+
<!-- If applicable, add information regarding the migration from a classic destination to an Actions-based version below -->
54+
55+
## Migration from the classic <destination_name> destination
56+
57+
<!-- Include any pertinent information here. -->

‎templates/partners/source.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# 💥 Segment Partner Source 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+
> At Segment, we believe that documentation is crucial in delivering the best experience for our mutual customers so we want to think with the following mindset:
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+
>+ Provide actionable code samples for each API method.
14+
>
15+
>+ If you would like to include screenshots, please send the original image to us via Slack with naming corresponding to where you've included it within the Markdown below. We prefer PNG images within 400px - 1200px. If you'd like to submit a GIF, please keep under 15MB. Generally you should be able to write these out as text, so only use them when there's something really hard to explain.
16+
>
17+
> The below template intends to provide a standardized structure. Please **make a copy** of this template for editing and submit to the Segment team as a new note on [HackMD.io](https://hackmd.io/). You can view a sample doc as reference here: https://segment.com/docs/sources/cloud-apps/klenty/.
18+
>
19+
> 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!
20+
>
21+
> If you have any questions in the meantime, please reach out to our team at [email protected].
22+
23+
24+
---
25+
26+
## Template begins here...
27+
28+
---
29+
title: YOURINTEGRATIONNAME
30+
---
31+
32+
> 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.
33+
34+
[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.
35+
36+
This is an [Event Cloud Source](https://segment.com/docs/sources/#event-cloud-sources) which can not only export data into your Segment warehouse, but they can also federate the exported data into your other enabled Segment Destinations.
37+
38+
> Update your company name and support email address.
39+
40+
This source is maintained by YOURINTEGRATION. For any issues with the source, [contact their Support team](mailto:[email protected]).
41+
42+
> Update your company name (x2) and support email address.
43+
44+
_**NOTE:** The YOURINTEGRATION Source is currently in beta, which means that they are still actively developing the source. This doc was last updated on January 23, 2019. If you are interested in joining their beta program or have any feedback to help improve the YOURINTEGRATION Source and its documentation, [let their team know](mailto:[email protected])!_
45+
46+
47+
## Getting Started
48+
49+
> Include clear, succinct steps including hyperlinks to where customers can locate the place in your app to enter their Segment writekey.
50+
51+
1. From your workspace's [Sources catalog page](https://app.segment.com/goto-my-workspace/sources/catalog) click **Add Source**.
52+
2. Search for "YOURINTEGRATION" in the Sources Catalog, select YOURINTEGRATION, and click **Add Source**.
53+
3. On the next screen, give the Source a name and configure any other settings.
54+
55+
The nickname is used as a label in the Segment app, and Segment creates a related schema name in your warehouse. The nickname can be anything, but we recommend using something that reflects the source itself and distinguishes amongst your environments (eg. SourceName_Prod, SourceName_Staging, SourceName_Dev).
56+
5. Click **Add Source** to save your settings.
57+
6. Copy the Write key from the Segment UI and log in to your YOURINTEGRATION account - navigate to Settings > Integrations > Segment Integration and paste the key to connect.
58+
59+
> For each of the below sections, populate the event and properties that a customer would expect to receive in their downstream tools from your Event Source.
60+
61+
## Events
62+
63+
The table below lists events that YOURINTEGRATION sends to Segment. These events appear as tables in your warehouse, and as regular events in other Destinations. YOURINTEGRATION includes the `userId` if available.
64+
65+
<table>
66+
<tr>
67+
<td>Event Name</td>
68+
<td>Description</td>
69+
</tr>
70+
<tr>
71+
<td>Email Sent</td>
72+
<td>Email was sent successfully</td>
73+
</tr>
74+
<tr>
75+
<td>Email Opened</td>
76+
<td>Prospect opened the email</td>
77+
</tr>
78+
<tr>
79+
<td>Link Clicked</td>
80+
<td>Prospect clicked the tracking link</td>
81+
</tr>
82+
<tr>
83+
<td>Email Replied</td>
84+
<td>Prospect replied to the email sent</td>
85+
</tr>
86+
<tr>
87+
<td>Email Bounced</td>
88+
<td>Email servers rejected the email</td>
89+
</tr>
90+
<tr>
91+
<td>Email Unsubscribed</td>
92+
<td>Prospect clicked the unsubscribe link</td>
93+
</tr>
94+
</table>
95+
96+
## Event Properties
97+
98+
The table below list the properties included in the events listed above.
99+
100+
<table>
101+
<tr>
102+
<td>Property Name</td>
103+
<td>Description</td>
104+
</tr>
105+
<tr>
106+
<td>`event`</td>
107+
<td>Email event type</td>
108+
</tr>
109+
<tr>
110+
<td>`userId`</td>
111+
<td>Prospect email ID</td>
112+
</tr>
113+
<tr>
114+
<td>`email_id`</td>
115+
<td>ID of the email</td>
116+
</tr>
117+
<tr>
118+
<td>`fromId`</td>
119+
<td>Sender email ID</td>
120+
</tr>
121+
<tr>
122+
<td>`email_subject`</td>
123+
<td>Subject line of the email</td>
124+
</tr>
125+
<tr>
126+
<td>`link`</td>
127+
<td>URL of the link clicked</td>
128+
</tr>
129+
</table>
130+
131+
## Adding Destinations
132+
133+
Now that your Source is set up, you can connect it with Destinations.
134+
135+
Log into your downstream tools and check to see that your events appear as expected, and that they contain all of the properties you expect. If your events and properties don’t appear, check the [Event Delivery](https://segment.com/docs/connections/event-delivery/) tool, and refer to the Destination docs for each tool for troubleshooting.
136+
137+
If there are any issues with how the events are arriving to Segment, [contact the YOURINTEGRATION support team](mailto:[email protected]).
138+
139+
---
140+
141+
> 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!

0 commit comments

Comments
 (0)