Skip to main content
@STYLE.md

​
Working relationship

  • Push back on ideas when you have good reason to — this leads to better documentation. Cite sources and explain your reasoning when you do.
  • When intent is unclear, state your interpretation and planned approach before editing.
  • Never lie, guess, or make up anything.

​
Project context

  • Format: MDX files with YAML frontmatter
  • Config: docs.json for navigation, theme, and settings — refer to the docs.json schema when modifying it
  • Components: Mintlify components

​
Content strategy

  • Search for existing content before adding anything new. Avoid duplication unless there is a strategic reason for it.
  • Check existing patterns before introducing new ones.
  • Start by making the smallest reasonable change.
  • Make content evergreen: avoid temporal language like “currently” or “as of now” (see STYLE.md for details).

​
Editorial policies

Standing “whether/what/where to document” decisions that a PR diff or release notes can’t convey on their own. Check a change against these before recommending or writing docs. If a change is covered by a hold, don’t-document, or placement policy, the correct output is that policy applied (hold, no docs, or the required placement) with the policy cited — not the nearest plausible edit. The team curates this list: when a review establishes a new standing policy, add a line here with a one-sentence rationale, and remove one when it no longer holds (for example, when a held feature ships). Hold until released:
  • Self-hosting features wait for a release. Do not publish documentation for a self-hosting or data-plane change until it ships in a released Terraform module (terraform-aws/google/azure-braintrust-data-plane) or Helm chart (helm) version. A merge to the monorepo does not reach self-hosted customers, and self-hosting docs are never auto-implemented.
  • Feature-flagged behavior is not GA. If a capability is gated behind a feature flag (for example, LaunchDarkly) or is otherwise not generally available, hold the docs until it ships by default, or mark it with <PublicPreview feature="..." verb="..." />. Never document flag-gated behavior as generally available. See Feature lifecycle for what each phase means, and add the feature to that page’s public preview table when you mark it.
Where to place:
  • Private preview features are documented on a real page, hidden by default and never excluded from the build. A private preview feature is invite-only, works end to end, and might not be documented publicly. This rule takes precedence over the feature-flag hold above: document the feature now instead of holding it, and don’t mark it with <PublicPreview> or add it to the public preview table (both are for public preview). Write it up on a normal page and choose its visibility:
    • Default: hide the page with both hidden: true and noindex: true. Mintlify’s hidden takes the page out of navigation, but not out of search here, because docs.json sets seo.indexing to all, which returns hidden pages to site search, sitemaps, search engine indexing, AI assistant context, and llms.txt. noindex: true restores the exclusion, and it isn’t sufficient on its own because it leaves the page in navigation. Don’t change seo.indexing to avoid the second key: one switch covers the whole site, and its default would de-index the hundreds of off-nav pages, mostly KB articles, that #15818 set it to all for. The page stays reachable by direct URL, so share that URL with invited customers and don’t link to it from indexed pages. admin/scim.mdx is a working example.
    • When the feature should be discoverable: publish the page normally (in navigation and search) with a <Note> callout that the feature is in private preview, available to a limited set of customers, and that readers should contact Braintrust to request access.
    Either way, include a callout stating that behavior can change and how to get access, and do not add the feature to the public preview table on Feature lifecycle. That table is for public preview only. Do not use .mintignore to exclude a preview page from the build or mirror it in Notion. That practice is retired.
Don’t document:
  • Internal-only concepts stay out of user-facing prose. Superuser or Sysadmin roles, hardcoded internal overrides, internal service names, and internal-only configuration are not user-facing. Document the behavior a customer observes, not the internal mechanism that produces it.
  • Preserve deferred content as deferred. Never uncomment or surface content the docs deliberately keep commented out or hidden. Commented-out blocks are held on purpose.
Changelog worthiness (what does and does not warrant a changelog entry) lives in the changelog-entry skill’s decision rule, not here.

​
Writing standards

  • Add alt text to all images.
  • Code samples should be complete and runnable where possible.