Skip to main content

​
Contribute public docs without creating drift

  1. Identify the user problem first: tutorial, how-to, reference, explanation, or support-routing change.
  2. Edit the route that owns that problem instead of adding a duplicate answer in a nearby page.
  3. Keep public and internal documentation boundaries explicit; do not move private runbook material onto the public Mintlify surface.
  4. Validate the page locally with Mintlify link checks and the repo-owned docs governance checks.
  5. Open or update the merge request with the governing issue and exact verification evidence.

​
Pick the correct docs surface first

If the contribution is about…Edit this surfaceDo not use this surface when…
public product, API, governance, or institutional docsdocs/** public routesthe content is internal workflow or controller doctrine
docs navigation, redirects, or Mintlify platform behaviordocs/docs.json, redirects, and Mintlify-owned platform filesyou only need to change prose on one route
internal workflow doctrine or repo-only runbooksrepo workflow docs outside the public route treethe audience is external docs readers

​
Keep the Diataxis contract intact

  1. Use tutorials for guided first-success lessons.
  2. Use how-to guides for one concrete task.
  3. Use reference pages for exact facts, enums, formulas, or tables.
  4. Use explanation pages for system rationale and design tradeoffs.
  5. Use support and audience routes as routers, not as substitute product pages.

​
Minimal validation loop

  1. Run mint broken-links.
  2. Run uv run --directory rust-packages/ddx-python/devtools --extra dev python -m admin_cli docs taxonomy-check --mode strict --scope all.
  3. Run uv run --directory rust-packages/ddx-python/devtools --extra dev python -m admin_cli docs governance-check --mode strict --scope all.
  4. If the change alters packet-governed issue work, run the packet verifier or planning packet-check that owns the issue.

​
Common contribution mistakes to avoid

MistakeBetter move
adding the same answer in multiple pagesstrengthen the owning route and link to it
mixing task steps into reference or explanation pagesmove the procedure into a how-to guide
inventing unpublished enterprise, operator, or legal contentkeep the page boundary-honest and route readers to public escalation paths
editing only prose when the real issue is nav or redirect ownershipupdate docs.json or redirects in the same change

​
Merge request checklist

  1. State which route owns the concept now.
  2. Include the exact validation commands you ran.
  3. Mention any redirect, nav, or hosted-parity implications.
  4. If the change closes a hierarchy or packet gap, say which one.

​
Boundary rules

  • This page is for the public docs/** surface, not for internal workflow doctrine or private operator runbooks.
  • Use Use DerivaDEX Docs with AI Tools for public AI-access mechanics, not for maintainer contribution workflow.
  • Use Support Channels if the public docs and current repo state disagree and you cannot resolve the conflict from published sources.

​
Next routes

Last modified on April 13, 2026