initial segment doc (#863)

fern/docs.yml

@@ -11,6 +11,8 @@ navigation:
         path: ./docs/pages/enable-api-playground.mdx
       - page: Configure Custom Domain
         path: ./docs/pages/configure-custom-domain.mdx
+      - page: Configure Segment for a new Customer 
+        path: ./docs/pages/configure-segment.mdx
   - api: FDR API Reference
     api-name: fdr
     display-errors: true

fern/docs/pages/configure-segment.mdx

@@ -0,0 +1,38 @@
+---
+title: How to Enable Segment for a New Customer
+description: Learn about how to enable analytics collection in Segment for a customer's docs site
+---
+
+<Steps>
+
+  ### Step 1: Navigate to Segment
+
+  Go to https://app.segment.com/buildwithfern/overview
+
+  ### Step 2: Connect Requested Analytics Destinations
+
+  Customers may request analytics in one or multiple destinations. You send data to destinations by connecting them to a source (https://app.segment.com/buildwithfern/sources/build_with_fern/overview). Example destinations are Posthog, Google Analytics, and Hubspot. 
+
+  Aside: Segment limits how many instances (25) of a single destination type we can connect to a single source. To get around this, we use Segment functions which pipe the data to our own analytics instance + send it to the customer's analytics instance with HTTP requests.
+
+  For destination where we use Segment functions you do NOT need to connect a new destination to the source, you'll simply update the destination function as described below. This is currently only configured for Posthog. 
+
+  For other destination types, simply add an instance of the destination type and follow the instructions in Segment to connect it to the customer's instance.
+
+  ### Step 3: Configure Destinations
+  Each destination may require some configuration:
+
+  For Posthog:
+
+    Background: we collect our own analytics in Posthog based on all buildwithfern docs sites in addition to sending data to our customers' Posthog instances. To enable this, we use Segment destination functions to route events to the customer's instance.
+
+    Substep 0: Get the customer's Posthog write key and docs domain (eg https://dev.hume.ai/intro)
+
+    Substep 1: Navigate to the 'Send Pageviews to Posthog' function (https://app.segment.com/buildwithfern/functions/catalog/ifnd_6642809e38542e19d398034e/edit/code)
+
+    Substep 2: Add a new entry to DESTINATION_MAP with k:v of docs_domain:posthog_write_key. For example if I want to send events on 'blake.docs.buildwithfern.com' to the Posthog instance with writekey 'abcdefg', I add 'blake.docs.buildwithfern.com': 'abcdefg' to the DESTINATION_MAP
+
+    Substep 3: Test! Use the built-in test function to grab sample events and run the updated function on them. You should get an 'Output: Success' message if everything goes smoothly. Try to test with at least 1 example from the new customer's site and 1 from a different docs site. 
+
+    Substep 4: Save and Deploy. Once you deploy your changes will go live and the events should start populating in the customer's Posthog instance.
+</Steps>