Merge pull request dubinc#819 from dubinc/improve-intro-docs

Improve intro docs
decagonhq · Apr 25, 2024 · 02c0b8f · 02c0b8f
2 parents 815039b + 5259539
commit 02c0b8f
Show file tree

Hide file tree

Showing 28 changed files with 253 additions and 315 deletions.
diff --git a/apps/docs/data-model.mdx b/apps/docs/data-model.mdx
@@ -0,0 +1,47 @@
+---
+title: Data model
+description: "A quick overview of how Dub is structured."
+---
+
+import WorkspaceResponse from "/snippets/workspace-response.mdx";
+import LinkResponse from "/snippets/link-response.mdx";
+import DomainResponse from "/snippets/domain-response.mdx";
+import TagResponse from "/snippets/tag-response.mdx";
+
+Whether you are using Dub's [API](/api-reference/introduction) or not, this page is a quick way to understand how Dub works.
+
+Within Dub, all data belongs to a [**Workspace**](#workspace). Within a workspace, you have [Links](#links), [Domains](#domains), [Tags](#tags), and more.
+
+## Workspace
+
+[Workspaces](https://dub.co/help/article/what-is-a-workspace) is the defacto way of organizing your links and working with your team on Dub. You can think of a Dub workspace like a workspace on Slack or Discord – it's a shared space where you can [invite your team members](https://dub.co/help/article/how-to-invite-teammates) to collaborate on links.
+
+When interacting with Dub's API, you will also need to specify the [Workspace ID](/api-reference/introduction#workspace-id) to perform any operation. You can find the workspace ID under the **General** settings page of your workspace.
+
+<Accordion title="Workspace model">
+  <WorkspaceResponse />
+</Accordion>
+
+## Links
+
+Links are the bread and butter of Dub. You can shorten any URL to a Dub link, which you can then share with your audience. Links can be [created](/api-reference/endpoint/create-a-new-link), [updated](/api-reference/endpoint/edit-a-link), and [deleted](/api-reference/endpoint/delete-a-link) via the [Dub API](/api-reference/introduction) or the [Dub dashboard](https://app.dub.co).
+
+<Accordion title="Link model">
+  <LinkResponse />
+</Accordion>
+
+## Domains
+
+On Dub, you can [add custom domains](https://dub.co/help/article/how-to-add-custom-domain) to create branded short links for better brand recognition. You can also [set a primary domain](https://dub.co/help/article/how-to-set-primary-domain) for it to be used as the default domain for new links (both via the API and the dashboard).
+
+<Accordion title="Domain model">
+  <DomainResponse />
+</Accordion>
+
+## Tags
+
+Tags are a way to organize your links. You can [add tags to your links](https://dub.co/help/article/how-to-use-tags) to categorize them and make them easier to find. You can also [filter analytics by tags](https://dub.co/blog/introducing-tags#filtering-analytics-by-tags) to get a better understanding of how your campaigns are performing.
+
+<Accordion title="Tag model">
+  <TagResponse />
+</Accordion>
diff --git a/apps/docs/examples.mdx b/apps/docs/examples.mdx
@@ -5,6 +5,14 @@ description: "Explore ideas and examples of what you can build with the Dub.co A
 ---
 
 <CardGroup cols={2}>
+  <Card
+    title="OSS Gallery"
+    icon="github"
+    href="https://github.com/dubinc/oss-gallery"
+    color="#333333"
+  >
+    Open-source gallery built with the Dub.co Typescript SDK
+  </Card>
   <Card
     title="Dublet"
     icon="github"

diff --git a/apps/docs/images/thumbnail.png → .../docs/images/logo-background-gradient.png b/apps/docs/images/thumbnail.png → .../docs/images/logo-background-gradient.png
diff --git a/apps/docs/images/thumbnail.jpg b/apps/docs/images/thumbnail.jpg
diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx
@@ -1,53 +1,63 @@
 ---
 title: Introduction
-"og:title": "Getting Started with Dub.co - Documentation"
-description: "Dub.co is the open-source link management infrastructure for modern marketing teams."
+"og:title": "Getting Started with Dub - Documentation"
+description: "Dub is the link management platform for modern marketing teams."
 ---
 
 <Frame>
   <img
     className="rounded-lg border border-gray-100"
-    src="https://assets.dub.co/thumbnail.jpg"
-    alt="Dub.co Thumbnail"
+    src="/images/thumbnail.jpg"
+    alt="Dub Thumbnail"
     width="1200"
     height="630"
   />
 </Frame>
 
+Our mission is to reimagine the role of links – one of the most foundational pieces of the web – from being a simple **"resource locator"** (URL) to a full **attribution engine** – visualizing the user journey from the first click to the final conversion event.
+
 ## Features
 
 Here are some of the features that Dub offers:
 
-- [Advanced Analytics](https://dub.co/features/analytics)
-- [Branded Links](https://dub.co/features/branded-links)
-- [QR Codes](https://dub.co/features/qr-codes)
-- [Personalization](https://dub.co/features/personalization)
-- [Team Collaboration](https://dub.co/features/collaboration)
-
-## Tech Stack
-
-Dub's codebase is [fully open-source](https://d.to/github) and is built on top of the following technologies:
-
-- [Next.js](https://nextjs.org/) – framework
-- [TypeScript](https://www.typescriptlang.org/) – language
-- [Tailwind](https://tailwindcss.com/) – CSS
-- [Upstash](https://upstash.com/) – redis
-- [Tinybird](https://tinybird.com/) – analytics
-- [PlanetScale](https://planetscale.com/) – database
-- [NextAuth.js](https://next-auth.js.org/) – auth
-- [BoxyHQ](https://boxyhq.com/enterprise-sso) – SSO/SAML
-- [Turborepo](https://turbo.build/repo) – monorepo
-- [Stripe](https://stripe.com/) – payments
-- [Postmark](https://postmarkapp.com/) – emails
-- [Vercel](https://vercel.com/) – deployments
+<AccordionGroup>
+  <Accordion title="Advanced Analytics" icon="chart-line">
+    Dub provides powerful analytics for your links, including geolocation,
+    device, browser, and referrer information. [Learn
+    more](https://Dub/features/analytics)
+  </Accordion>
+  <Accordion title="Branded Links" icon="link">
+    Dub offers free custom domains on all plans for you to create branded links
+    that stand out. [Learn more](https://Dub/features/branded-links)
+  </Accordion>
+  <Accordion title="QR Codes" icon="qrcode">
+    QR codes and short links are like peas in a pod. Dub offers free QR codes
+    for every short link you create – both via our dashboard and
+    [programmatically](/api-reference/endpoint/retrieve-a-qr-code). [Learn
+    more](https://Dub/features/qr-codes)
+  </Accordion>
+  <Accordion title="Personalization" icon="user">
+    Customize your link's behavior with [device
+    targeting](https://Dub/help/article/device-targeting), [geo
+    targeting](https://Dub/help/article/geo-targeting), [link
+    expiration](https://Dub/help/article/link-expiration), [link
+    cloaking](https://Dub/help/article/link-cloaking), and more. [Learn
+    more](https://Dub/features/personalization)
+  </Accordion>
+  <Accordion title="Team Collaboration" icon="users">
+    Invite your teammates to collaborate on your links. For enterprises, Dub
+    offers [SAML SSO](https://Dub/help/category/saml-sso) for better security.
+    [Learn more](https://Dub/features/collaboration)
+  </Accordion>
+</AccordionGroup>
 
 ## Getting Started
 
 To get started with Dub, you can do any of the following:
 
 <CardGroup cols={2}>
-  <Card title="Create a free account" icon="code" href="https://app.dub.co">
-    Create a free account to get started with Dub
+  <Card title="Quickstart Guide" icon="code" href="/quickstart">
+    Follow our quickstart guide to get started with Dub
   </Card>
   <Card title="Try our API" icon="code" href="/api-reference/introduction">
     Learn how to use Dub's API to create and manage links programmatically

diff --git a/apps/docs/local-development.mdx b/apps/docs/local-development.mdx
@@ -6,8 +6,8 @@ description: "A guide on how to run Dub.co's codebase locally."
 
 <Frame>
   <img
-    src="/images/thumbnail.png"
-    alt="Dub.co Thumbnail"
+    src="/images/logo-background-gradient.png"
+    alt="Dub.co Logo on a gradient background"
     width="1200"
     height="630"
   />

diff --git a/apps/docs/mint.json b/apps/docs/mint.json
@@ -56,12 +56,16 @@
   "navigation": [
     {
       "group": "Getting Started",
-      "pages": ["introduction", "local-development", "self-hosting"]
+      "pages": ["introduction", "data-model"]
     },
     {
       "group": "Resources",
       "pages": ["integrations", "examples"]
     },
+    {
+      "group": "Open source",
+      "pages": ["local-development", "self-hosting"]
+    },
     {
       "group": "API Reference",
       "pages": [

diff --git a/apps/docs/quickstart.mdx b/apps/docs/quickstart.mdx
@@ -0,0 +1,14 @@
+---
+title: Quickstart
+description: "Everything you need to start using Dub.co"
+---
+
+<Frame>
+  <img
+    className="rounded-lg border border-gray-100"
+    src="/images/thumbnail.jpg"
+    alt="Dub.co Thumbnail"
+    width="1200"
+    height="630"
+  />
+</Frame>
diff --git a/apps/docs/sdks/typescript/domains/add.mdx b/apps/docs/sdks/typescript/domains/add.mdx
@@ -42,6 +42,8 @@ import DomainResponse from "/snippets/domain-response.mdx";
   an example of a link to be shortened.
 </ParamField>
 
+## Response
+
 <DomainResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/domains/list.mdx b/apps/docs/sdks/typescript/domains/list.mdx
@@ -10,6 +10,8 @@ import DomainResponse from "/snippets/domain-response.mdx";
 
 No arguments.
 
+## Response
+
 <DomainResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/domains/set-primary.mdx b/apps/docs/sdks/typescript/domains/set-primary.mdx
@@ -12,6 +12,8 @@ import DomainResponse from "/snippets/domain-response.mdx";
   Name of the domain to set as primary. Eg. `acme.com`.
 </ParamField>
 
+## Response
+
 <DomainResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/domains/transfer.mdx b/apps/docs/sdks/typescript/domains/transfer.mdx
@@ -16,6 +16,8 @@ import DomainResponse from "/snippets/domain-response.mdx";
   The ID of the new workspace to transfer the domain to.
 </ParamField>
 
+## Response
+
 <DomainResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/domains/update.mdx b/apps/docs/sdks/typescript/domains/update.mdx
@@ -43,6 +43,8 @@ import DomainResponse from "/snippets/domain-response.mdx";
   an example of a link to be shortened.
 </ParamField>
 
+## Response
+
 <DomainResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/links/create-many.mdx b/apps/docs/sdks/typescript/links/create-many.mdx
@@ -92,6 +92,8 @@ import LinkResponse from "/snippets/link-response.mdx";
   The Android destination URL for the short link for Android device targeting.
 </ParamField>
 
+## Response
+
 <LinkResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/links/create.mdx b/apps/docs/sdks/typescript/links/create.mdx
@@ -92,6 +92,8 @@ import LinkResponse from "/snippets/link-response.mdx";
   The Android destination URL for the short link for Android device targeting.
 </ParamField>
 
+## Response
+
 <LinkResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/links/get.mdx b/apps/docs/sdks/typescript/links/get.mdx
@@ -17,6 +17,8 @@ import LinkResponse from "/snippets/link-response.mdx";
   The key of the link to retrieve. E.g. for `d.to/github`, the key is `github`.
 </ParamField>
 
+## Response
+
 <LinkResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/links/list.mdx b/apps/docs/sdks/typescript/links/list.mdx
@@ -50,6 +50,8 @@ import LinkResponse from "/snippets/link-response.mdx";
   The page number for pagination (each page contains `100` links).
 </ParamField>
 
+## Response
+
 <LinkResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/links/update.mdx b/apps/docs/sdks/typescript/links/update.mdx
@@ -90,6 +90,8 @@ import LinkResponse from "/snippets/link-response.mdx";
   The Android destination URL for the short link for Android device targeting.
 </ParamField>
 
+## Response
+
 <LinkResponse />
 
 <RequestExample>

diff --git a/apps/docs/sdks/typescript/tags/create.mdx b/apps/docs/sdks/typescript/tags/create.mdx
@@ -4,6 +4,8 @@ title: "Create"
 description: "Create a new tag for the authenticated workspace."
 ---
 
+import TagResponse from "/snippets/tag-response.mdx";
+
 ## Arguments
 
 <ParamField body="tag" type="string" required>
@@ -17,17 +19,7 @@ description: "Create a new tag for the authenticated workspace."
 
 ## Response
 
-<ResponseField name="id" type="string" required>
-  The unique ID of the tag.
-</ResponseField>
-
-<ResponseField name="name" type="string" required>
-  The name of the tag.
-</ResponseField>
-
-<ResponseField name="color" type="string" required>
-  The color of the tag.
-</ResponseField>
+<TagResponse />
 
 <RequestExample>
 
@@ -49,4 +41,4 @@ await dub.tags.create({
 }
 ```
 
-</ResponseExample>
+</ResponseExample>
diff --git a/apps/docs/sdks/typescript/tags/list.mdx b/apps/docs/sdks/typescript/tags/list.mdx
@@ -4,19 +4,11 @@ title: "List"
 description: "Retrieve a list of tags for the authenticated workspace."
 ---
 
-## Response
-
-<ResponseField name="id" type="string" required>
-  The unique ID of the tag.
-</ResponseField>
+import TagResponse from "/snippets/tag-response.mdx";
 
-<ResponseField name="name" type="string" required>
-  The name of the tag.
-</ResponseField>
+## Response
 
-<ResponseField name="color" type="string" required>
-  The color of the tag.
-</ResponseField>
+<TagResponse />
 
 <RequestExample>