Skip to main content

​
Working on the Dovetail help center

This repo powers dovetail.com/help. It’s a Mintlify site: pages are .mdx, navigation lives in docs.json, and merges to main deploy automatically. Read this before editing content.

​
The one rule that matters most

Never state a product fact you haven’t verified. The help center is support-facing — a wrong plan name, UI label, or capability claim creates tickets and erodes trust. Marketing copy on dovetail.com is often ahead of what has actually shipped. Verify in this order:
  1. The product codebase at ~/Code/platform — the source of truth for UI labels, action names, and behavior. See “Checking the product” below.
  2. Other pages in this repo — if an existing page states it plainly, you can repeat it.
  3. dovetail.com — good for positioning and naming, but it may describe things that aren’t live yet.
If you can’t verify it, leave it out and flag it. An incomplete page beats a confidently wrong one.

​
Live contradictions to be careful about

These are known conflicts between sources. Don’t “resolve” them by picking whichever reads better — ask.
  • Agent invocation in Slack and Teams. Digital Twins can be invoked in Slack and Teams with @Dovetail +<twin name> (the + is required, even if code review suggests otherwise), and stay in persona for the thread. Only people whose Slack or Teams account is linked to a Dovetail user can invoke a twin; anyone in the connected workspace can query with @Dovetail (confirmed by the docs team, October 2026; documented in help/chat/chat-in-slack-and-teams). Weekly wraps and scheduled summaries come from agents (the Send Slack message tool) and post to Slack only, not Teams. Invoking other agents there is still “coming soon” in help/agents.mdx — don’t extend the twin behavior to agents generally without confirmation. Agents delivering output to Slack, Teams, or email is separate and is documented.
  • Plans. The docs don’t refer to plans. See Plans and pricing.

​
Current product positioning

Dovetail is an AI-native customer intelligence platform, not a research repository. Research repository is one use case among several. The platform narrative is Centralize → Analyze → Query → Act: Lead with Agents, Digital Twins, and Channels. Projects is fully supported but is no longer the front door.

​
Channels 1.0 vs 2.0

Channels 2.0 is the default for new channels and is still in beta. Sources are part of the Channels 2.0 beta: 2.0 channels add their data from the workspace’s sources. Channels created before 2.0 stay on 1.0, which is being retired.
  • 2.0 terminology: Ideas (ranked, revenue-weighted groupings of feedback) and Evidence (the underlying data points). Documented in help/channels/index.mdx and the other help/channels/* pages.
  • 1.0 terminology: themes and topics. Documented in help/channels/channels-1-0.mdx, which is labeled Legacy.
Don’t rename “themes” to “ideas” in 1.0 content or in Projects — canvas clustering legitimately uses “themes”.

​
Terminology

  • Insights → Docs. The product object is a doc. Generic English (“uncover insights”) is fine, as are API identifiers like insight:read, and a third party’s own naming, like Productboard Insights.
  • Magic → AI. AI summaries, AI highlights, AI clustering, and Automation. The blue magic shuriken icon keeps its name — that’s the actual UI element.
  • Digital Twins — both words capitalized. It’s a product name.
  • Ask Dovetail is retired as a name. It’s just querying Dovetail with @dovetail in Slack or Teams. The old /dovetail digest and create-digest digests are gone, replaced by agents posting to Slack.
  • Taxonomy is acceptable in a research operations or research repository context, where it’s the practitioner’s word for a shared tag and field structure. It is not how we describe the product or lead onboarding content — that framing is what the September 2026 audit removed.
  • Research repository is one use case, not the category. The category is customer intelligence platform.
  • Users. Everyone in a workspace is a user. Don’t write “member”, “person”, or “seat” for someone in the workspace, and don’t mention user roles (Manager, Contributor, Viewer) or paid seats in new content. Describe access by what it is: workspace admin, edit access to a channel, Can use on a source. help/user-roles stays as the reference for legacy paid plans until roles are retired, so leave existing role documentation alone.
  • Sources. “Sources” is the feature and the sidebar item; “a source” is one connection (“the Zendesk source”). A source imports datasets (a Slack channel, a Gong team, a Zendesk group). Customer feedback sources bring in data points; customer context sources (CRM enrichment: Salesforce Contacts, HubSpot Contacts) add details to contacts. Can use decides who can add a source’s data to a channel; the channel’s own permissions decide who sees it. Workspace admins create sources. Don’t write “data source” or “integration” for a source in steps. CSV uploads aren’t sources. The concepts live on help/sources/*; link there rather than re-explaining.
  • Connected apps. Settings → Connected apps (formerly Integrations) holds each user’s own app connections: MCP connectors, calendars and recorders, file storage, and send-to tools. Each user connects their own account. Documented in help/connected-apps.
  • Redaction is chosen where data comes in: on each source, during a CSV upload to a channel, during a project import, and on each calendar connection. Projects and channels don’t have redaction settings of their own.

​
Plans and pricing

The public pricing page shows a single offering, and the docs don’t refer to plans:
  • Don’t name plans or add plan entitlement callouts in new content. Existing “Available on the Enterprise plan” callouts predate this rule. Remove them when you rewrite a page, but don’t make a separate pass for them.
  • Legacy customers are the one exception. Where behavior differs for customers on older plans, say “legacy paid plans”. Never name Professional, Business, or Free as something to buy.
  • The Free plan is being retired. Don’t write new Free-specific content. If an existing page states a Free limit, workspaces/libraries/app-lib/src/billing/productRestrictions.ts in ~/Code/platform is the source of truth.
  • Pricing is credits. Usage draws from a workspace’s shared credit balance, and help/credits-and-usage is the one home for how credits work. Link there rather than restating it.
    • State credit amounts only, such as “1 credit per data point”. Never state prices, per-credit rates, platform or user fees, or discounts. Dovetail’s pricing details are not public.
    • Don’t include release or migration timelines (“from December”, “starting in October”). Rollouts are communicated separately; the docs describe mechanics.
    • Don’t document billing controls before they ship, such as overage settings or the Usage page.
  • Don’t gate a page and then grant the feature elsewhere in the same callout. The free-plan-contradiction linter rule catches the Free version of this.

​
Writing style

Follow benjaminhumphrey.com/style.

​
Tone

Boring is the target. This is enterprise help documentation: professional, matter-of-fact, concise, and clear. It is not marketing copy, and it is not an essay. These patterns read as AI-generated and don’t belong here: Value and ROI framing is welcome, but state it as an outcome, plainly. “Prioritization can be based on revenue rather than request volume” is the value claim — it needs no flourish. Never invent evidence for it: no statistics, percentages, time savings, or dollar figures that aren’t sourced. Ground value in a mechanism the docs describe. If a sentence sounds like it was written to be quoted, rewrite it.

​
Mechanics

The rules that come up most here:
  • US English always. Organize, analyze, customize, center. Dovetail is Australian; the docs are not.
  • Sentence case for titles and headings. Proper nouns keep their capitals: Dovetail, Channels, Agents, Docs, Digital Twins, Slack, Jira.
  • “and”, not ”&” — except inside a third-party UI label you’re quoting (“Attributes & Claims” in Entra).
  • Active voice. Short, varied sentences. Simple language over jargon.
  • Oxford comma. Em dash (—) for strong breaks. Curly quotes, never straight ones (straight quotes only in code and HTML attributes).
  • Spell out zero through nine; digits for 10 and up.
  • Never write “click here” — describe the destination.

​
Titles

  • Keep sidebar labels under ~26 characters so they don’t wrap to two lines.
  • Use sidebarTitle for the short label and title for the fuller, descriptive page heading when they need to differ.
  • No two pages should share a sidebar label. Two “Digital Twins” entries in one sidebar is a real bug that shipped once already.

​
Structure

docs.json groups are ordered deliberately: orientation, then connecting data, then value and impact, then core surfaces, then technical and administrative material. Within a group, the overview or index page comes first and everything else is alphabetical by sidebar label. Two content layers, and both matter:
  • Feature reference — organized by product surface, named the way people search (“Channels”, “Highlights”). The bulk of the site.
  • Outcome and use case — goal-shaped pages like help/voice-of-customer and help/agents-use-cases that explain what you’re trying to achieve and route down into the reference layer. Don’t duplicate steps here; link to them.
When you add a page, add it to docs.json. When you delete or move one, add a redirect in the same file.

​
One home per topic

Each procedure lives on exactly one page. Everything else links to it. The Docs content used to exist twice — help/projects/docs duplicated ten of the twelve sections in help/docs/ — which meant two pages to keep in sync and two competing search results. The split now is:
  • help/docs/* — how docs work anywhere in the workspace: creating, editing, formatting, sharing, presenting, metrics.
  • help/projects/docs — only what’s specific to docs inside a project: building one from your highlights, referencing project data, keeping those references current, project fields.
Before adding a section, search for its heading elsewhere in the repo. If it already exists, link instead.

​
Every page needs frontmatter

description is the search snippet and the meta description — it is not optional. Don’t add og:image unless the file actually exists on disk; the site-level fallback in docs.json is better than a broken path. Write real alt text on every image. Filename-derived junk (“Clean Shot 2026 07 16 At 15 14 55@2x”, “Hero Pn”) is useless to screen readers and to search. Describe what the image shows, in 5–12 words.

​
Before you commit

The linter masks code, links, URLs, and file slugs, so it won’t flag a British spelling inside a filename like organise-and-share-docs. It checks: A page can opt out of one rule with {/* lint-disable <rule-id> */} anywhere in the file. Use it only where the repetition is deliberate — integrations/gong.mdx runs parallel Channels and Projects walkthroughs that share screenshots — and name the rule you mean rather than disabling the lot. Deliberately not flagged, so don’t “fix” these:
  • “Magic summary” and similar feature names — they may still be live product names. Confirm with product first.
  • A vendor’s own object name, like “Usersnap feedback item”.
The two duplication rules exist because the Mintlify dashboard editor has twice written edits back as insertions rather than replacements, leaving new text beside the old copy instead of over it. That produced Start hereStart hereStart hereStart here on the home page, and a whole duplicated section on help/security-information and help/channels/channel-setup that sat live on the site for days. Those commits land on main as mintlify[bot] with Mintlify-Source: dashboard-editor. The same sync also drops content — three cards off the home page, a description off a frontmatter — so when you see duplication, diff the whole bot commit rather than only deleting the extra copy. Also check that internal links and heading anchors resolve. Mintlify’s heading anchors keep curly apostrophes, em dashes, and slashes (only ASCII punctuation is dropped), which lint-structure doesn’t model, so keep those characters out of headings that other pages link to. Also check that any image you reference actually exists on disk. Links pointing at dovetail.com/help/* are usually stale — the current docs are at docs.dovetail.com, and root-relative paths (/help/channels) are preferred for internal links.

​
Checking the product

~/Code/platform is a 19GB Nx monorepo. Recursive grep and find across it are unreliable from a sandboxed shell — they can return nothing rather than failing loudly, so a zero-result grep there is not evidence of absence. Run a control search for a term you know exists before trusting a negative result. Narrow, targeted reads do work. Useful locations:
  • workspaces/apps/zapier/src/creates and .../triggers — Zapier action and trigger labels. This is how we learned the Zapier action is “Add Doc to Project”, not “Create Insight”.
  • workspaces/apps/web-app/src/components — UI components.
  • workspaces/services/mcp — MCP server.

​
History worth knowing

A large content audit ran in September 2026. It deleted the Academy (27 pages), the taxonomy-led onboarding track, “How Dovetail is organized”, and several superseded duplicates including root-level copies of pages that had already moved into help/agents/. Two lessons from it:
  1. Terminology drift is the main failure mode. Insights were renamed to Docs, and the docs took months to catch up — the rename was still half-finished across ten pages. The linter exists to catch the next one.
  2. Delete rather than caveat. A page describing a migration to a plan that no longer exists is worse than no page. Remove it and add a redirect.