Documentation improvements (#276)

parcelvoy · Oct 9, 2023 · 1875a8c · 1875a8c
1 parent 196a48e
commit 1875a8c
Show file tree

Hide file tree

Showing 21 changed files with 186 additions and 7 deletions.
diff --git a/docs/docs/how-to/campaigns/_category_.json b/docs/docs/how-to/campaigns/_category_.json
@@ -1,8 +1,5 @@
 {
     "label": "Campaigns",
-    "position": 1,
-    "link": {
-      "type": "generated-index"
-    }
+    "position": 1
   }
 
diff --git a/docs/docs/how-to/campaigns/create.md b/docs/docs/how-to/campaigns/create.md
@@ -0,0 +1,24 @@
+---
+title: Create
+---
+
+# Create a Campaign
+
+You can create a new campaign by clicking the `Create Campaign` button in the top right hand side of the `Campaigns` tab or through the action tile inside of a journey. In both cases, a modal will open with a list of options that are required in order to create a campaign.
+
+![Create Campaign](/img/campaigns_create_modal.png)
+### Fields
+#### General
+- **Name**: This is what will appear in lists and other places as the name of the campaign.
+- **Tags**: If you have created any tags, this option will appear allowing you to select tags so you can filter by them later.
+
+#### Lists
+This is how you target what users will receive you campaign. A master list is generated by subtracting any users in exclusion lists from users in send lists.
+- **Send Lists**: The lists of users you want to send the campaign to. The lists are combined to create one master list without any duplicates.
+- **Exclusion Lists**: What lists of users you want to exclude from being sent to. Any users in an exclusion list will be removed from the list of users to send the campaign to.
+
+#### Channel
+- **Medium**: The type of message to send. One of either: email, text (SMS), push notification, webhook.
+- **Provider**: Which integration you want to use to send the campaign. Parcelvoy handles the orchestration of sending a message, but uses third parties as the pipes to deliver the message to the end user. 
+- **Subscription Group**: What group to associate this message with. Subscription groups allow a user to unsubscribe from a given set of messages from you. It's recommended to create different groups for different types of messages you might send over a given channel.
+
diff --git a/docs/docs/how-to/campaigns/design.md b/docs/docs/how-to/campaigns/design.md
@@ -0,0 +1,55 @@
+---
+title: Design
+---
+
+# Design a Campaign
+Each campaign is made up of a series of templates, each representing a given locale (language). After your campaign has been created, you can navigate to the `Design` tab to get started and create a template. 
+
+![Design Campaign](/img/campaigns_design.png)
+
+## Create Template
+Selecting `Create Template` will open a modal with various options depending on the channel of the campaign, but all of them require selecting a locale. If you dont have any already, create one, otherwise pick the locale you are targeting from the list!
+
+![Design Campaign Modal](/img/campaigns_design_template.png)
+
+### Locales
+A locale is a set of parameters that defines the user's language, region and any special variant. They can be anything from as broad a category as a language at large (`es` for Spanish) to as specific as a dialect (`en_PH` for English from the Philippines).
+
+## Design
+Once you have created a template you can begin designing it! Each channel that a campaign can be sent over has different editors that can be used to customize what you are sending.
+
+### Email
+You have by far the most customizeability when sending emails. You are able to adjust the entire design to be anything you would like. There are two different options for designing emails and the editor will vary based on your selection.
+
+#### Visual
+The visual editor provides you with a drag-and-drop interface for crafting emails without having to write any code. On the right hand side you are provided with different basic building blocks which you can drag in. Each block can then be customized to have specific styles or layouts.
+
+![Design Campaign Visual](/img/campaigns_design_visual.png)
+
+#### Code
+If you select to code the email yourself, you are given a code editor window that you can use. This editor allows for many of the conveniences of modern code editors like code suggestions and collapsing. You are also able to import uploaded images directly. Handlebars templating can be used throughout to autopopulate data directly from the user.
+
+![Design Campaign Code](/img/campaigns_design_code.png)
+
+### Text
+There is no customizeability available for text messages, the only thing you can configure is the body. The provided field accepted Handlebars so you can include user attributes as desired. To edit the body of the text, just hit the `Edit` button in the left hand column.
+
+By default, the render of the message shows you what it would look like inside of a phone.
+
+![Design Campaign Text](/img/campaigns_design_text.png)
+
+#### Opt Out
+Carriers typically require you to send opt out verbiage to a user so they know how they can stop receiving messages. Parcelvoy handles users unsubscribing from receiving text messages automatically for you if you've appropriately configured your provider.
+
+The opt out verbiage can be configured under project settings and will only be sent included in the very first text message you send to a user. Subsequent messages will not include it.
+
+### Push Notification
+Push notification vary in design OS by OS and phone by phone. Every design however contains the same two basic building blocks: `title` and `body`. 
+
+All fields availabe on push notifications allow for Handlebars templating.
+
+The `deeplink` field will cause the app to automatically navigate to that URL when a user opens the push notification.
+
+If you want to pass custom information down to your application so that you can process it, you can utilize the `Raw JSON` field.
+
+![Design Campaign Push](/img/campaigns_design_push.png)
diff --git a/docs/docs/how-to/campaigns/index.md b/docs/docs/how-to/campaigns/index.md
@@ -0,0 +1,34 @@
+---
+title: Campaigns
+sidebar_position: 1
+pagination_prev: null
+pagination_next: null
+custom_edit_url: null
+---
+
+import Card from '@site/src/components/Card'
+import Cards from '@site/src/components/Cards'
+
+# Campaigns
+
+## Overview
+Campaigns are how all messaging happens within Parcelvoy. Whether that be sending an email blast or calling a webhook inside of a journey, all of that uses a campaign.
+
+There are four basic channels that campaigns can be sent over:
+- Email
+- Text (SMS)
+- Push Notification
+- Webhook
+
+The campaign handles scheduling, targeting and designing of a given communication and then passes the transmission over to a provider.
+
+Diver deeper into the documentation for how to create, manage and launch campaigns.
+
+## Tutorials
+
+<Cards>
+    <Card title="Create" href="/how-to/campaigns/create">Start here to get up and running and get aquainted at a high level with Parcelvoy.</Card>
+    <Card title="Design" href="/how-to/campaigns/design">Design, preview and proof campaigns to make sure they are perfect!</Card>
+    <Card title="Launch" href="/how-to/campaigns/launch">Schedule, launch and evaluate how your campaigns are performing.</Card>
+    <Card title="Customize" href="/how-to/campaigns/templates">Templates are the backbone of campaigns and allow you to create dynamic messages.</Card>
+</Cards>
diff --git a/docs/docs/how-to/campaigns/launch.md b/docs/docs/how-to/campaigns/launch.md
@@ -0,0 +1,36 @@
+---
+title: Launch
+---
+
+# Launch a Campaign
+Once your campaign is designed and ready, you can send it to your targetted list. To send a campaign, hit the `Launch Campaign` button on the top right hand side. 
+
+![Launch Campaign](/img/campaigns_launch.png "Campaigns Launch")
+
+### Scheduling
+When you are ready to launch, you can chose if you want messages to go out immediately or be scheduled for some time in the future.
+
+#### Now
+This will immediately start enqueing emails to be sent out. Selecting this option is great for anything you are ready to send but it does not allow you to abort the campaign since everything goes out immediately.
+
+![Launch Campaign Modal](/img/campaigns_launch_modal.png)
+
+#### Schedule
+If you opt to schedule a campaign to go out in the future you can specify a time and date to begin the send. By default the date and time you select are in the projects selected timezone.
+
+![Launch Campaign Schedule](/img/campaigns_launch_schedule.png)
+
+##### Send In Users Timezone
+You can override sending a campaign in your projects default and better target your users by utilizing the `Send In Users Timezone` functionality. To enable this, just toggle that option. We highly recommend selecting this option if you have a global userbase.
+
+If you have this toggle selected a message will go out at the selected time in the users timezone. For example if you opt for a message to go out at 7:00am, this means that a user in Madrids message would send at 5:00 UTC wereas a user in Chicagos message would send seven hours later.
+
+Because of variations in timezones it is important to note that you should schedule any campaigns you wish to go out in the users timezone at least 24hrs in advance otherwise the selected time for that users timezone may have already passed. If a given time has already passed, the campaign will send immediately.
+
+### Aborting
+You can abort a campaign at any time, however messages may have already been sent. Aborting a campaign happens immediately and cancels any pending sends. 
+
+#### Restarting
+If you wish to resume a campaign that has been aborted it will not resend to any users who have already received a previous message. Only users who have not received the campaign will receive a restarted campaigns message.
+
+### Delivery
diff --git a/docs/docs/how-to/index.md b/docs/docs/how-to/index.md
@@ -0,0 +1,19 @@
+---
+title: How To
+sidebar_position: 1
+pagination_prev: null
+pagination_next: null
+custom_edit_url: null
+---
+
+import Card from '@site/src/components/Card'
+import Cards from '@site/src/components/Cards'
+
+# How To
+
+<Cards>
+    <Card title="Campaigns" href="/how-to/campaigns">Get up and running sending messages to your users.</Card>
+    <Card title="Lists" href="/how-to/lists">Target and segment users based on provided criteria.</Card>
+    <Card title="Users" href="/how-to/users">Details on how to manage and import users.</Card>
+    <Card title="Settings" href="/how-to/settings">Overview of availabe settings to configure your projects.</Card>
+</Cards>
diff --git a/docs/docs/how-to/lists.md b/docs/docs/how-to/lists.md
@@ -1,6 +1,10 @@
+---
+title: Lists
+sidebar_position: 2
+---
+
 # Lists
 Lists allow you to group sets of users together to target them for messages. There are two different kinds of lists:
 - **Dynamic**: These lists generate themselves based on a set of criteria/rules that are set. After the initial list of users is generated, any users who fall into the criteria moving forward will find themselves added to the list.
 - **Static**: These are lists that are fixed and do not change on their own. The subset of users within them comes from an uploaded CSV document.
 
-## Creating a List
diff --git a/docs/docs/how-to/settings/_category_.json b/docs/docs/how-to/settings/_category_.json
@@ -1,5 +1,5 @@
 {
     "label": "Settings",
-    "position": 3
-  }
+    "position": 4
+}
 
diff --git a/docs/docs/how-to/users.md b/docs/docs/how-to/users.md
@@ -1,3 +1,8 @@
+---
+title: Users
+sidebar_position: 3
+---
+
 # Users
 This section contains a list of every single user that Parcelvoy can target. Users can be imported either via API or our client libraries. At its core, each user is a data record that contains a set of reserved properties (email, etc) as well as custom properties that you define.
 

diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css
@@ -204,4 +204,9 @@ h1, h2, h3, h4, h5, h6 {
 .markdown a.hash-link:hover {
     color: var(--color-primary);
     /* text-decoration: underline; */
+}
+
+.markdown p img {
+    border-radius: 8px;
+    box-shadow: 0 8px 20px rgba(0,0,0,0.2);
 }
diff --git a/docs/static/img/campaigns_create.png b/docs/static/img/campaigns_create.png
diff --git a/docs/static/img/campaigns_create_modal.png b/docs/static/img/campaigns_create_modal.png
diff --git a/docs/static/img/campaigns_design.png b/docs/static/img/campaigns_design.png
diff --git a/docs/static/img/campaigns_design_code.png b/docs/static/img/campaigns_design_code.png
diff --git a/docs/static/img/campaigns_design_push.png b/docs/static/img/campaigns_design_push.png
diff --git a/docs/static/img/campaigns_design_template.png b/docs/static/img/campaigns_design_template.png
diff --git a/docs/static/img/campaigns_design_text.png b/docs/static/img/campaigns_design_text.png
diff --git a/docs/static/img/campaigns_design_visual.png b/docs/static/img/campaigns_design_visual.png
diff --git a/docs/static/img/campaigns_launch.png b/docs/static/img/campaigns_launch.png
diff --git a/docs/static/img/campaigns_launch_modal.png b/docs/static/img/campaigns_launch_modal.png
diff --git a/docs/static/img/campaigns_launch_schedule.png b/docs/static/img/campaigns_launch_schedule.png