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 and Digital Twin invocation in Slack and Teams. dovetail.com says you can talk to a Digital Twin in Chat, Slack, or Teams. help/agents.mdx says invoking an agent in Teams and Slack is “coming soon”, and help/chat/chat-in-slack-and-teams documents only generic Ask Dovetail Q&A. The docs currently claim Chat only. Agents delivering output to Slack, Teams, or email is separate and is documented.
  • Plan entitlements. Entitlement callouts state what a reader can buy today, so they name Enterprise only: “Available on the Enterprise plan.” Retired plans are never named in them. Where behavior genuinely differs for customers still on a retired plan, describe it as “legacy paid plans” rather than naming Professional or Business.

​
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. Channels created before 2.0 stay on 1.0.
  • 2.0 terminology: Ideas (ranked, revenue-weighted groupings of feedback) and Evidence (the underlying data points). Documented in help/channels/channels-beta.mdx.
  • 1.0 terminology: themes and topics. Documented in help/channels/index.mdx, which is explicitly labeled as the 1.0 experience.
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.
  • 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.

​
Plans

Dovetail sells a Free plan and an Enterprise plan. There is no self-serve paid tier — Enterprise goes through Sales. Professional and Business are retired: existing customers keep them, but nobody can subscribe or resubscribe. Never present them as purchasable.

​
What the Free plan actually includes

Source of truth: workspaces/libraries/app-lib/src/billing/productRestrictions.ts in ~/Code/platform. Two free definitions are marked Status: Active — freeJul2025 (current) and freeMar2024 — so check both before writing a Free claim. In that file null means unlimited and 0 or false means unavailable; ProjectService enforces it as maximumProjects !== null && active_count >= maximumProjects. On the current Free plan (freeJul2025): Two traps this has already caused:
  • “Paid seat” is a seat type, not a statement about paying. On Free plans without user roles every user is assigned a paid seat, so “requires a paid seat” does not mean “requires payment”. Say what a role can do, and add “On plans without user roles, any user can.”
  • Don’t gate a page to Enterprise and then grant the feature on Free in the same callout. The free-plan-contradiction linter rule catches 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: 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”.
Also check that internal links and heading anchors resolve, and 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.