Contributing

All public RetainDB docs live in retaindb-frontend/docs. The job is not just to add information. The job is to make the next developer faster and less confused than they were before your change.

Before you open a PR

Ask these questions first:

1. should this be a standalone page at all?
2. who is the page for?
3. what is the first question that reader is asking?
4. can I prove the examples against the real implementation?

If you cannot answer those, stop before you start writing.

Where docs live

• content: retaindb-frontend/docs/*.mdx
• Mintlify config: retaindb-frontend/mint.json
• docs navigation config: retaindb-frontend/docs/docs.json
• docs validation: retaindb-frontend/scripts/validate-docs.mjs

Frontmatter rules

Every public page should declare:

• title
• description
• category
• page_type
• quality_tier
• updated_at

Use optional fields only when they add real meaning:

• version_track
• applies_to
• availability
• hide_feedback

Do not add applies_to as filler.

Writing rules

• write to the discovering developer, not the builder
• open with outcome, not taxonomy
• use one primary job per page
• prefer examples that a reader could actually run
• comments in code should explain why, not narrate syntax
• remove internal QA language from public docs

Page-type rules

Choose the page shape deliberately:

• quickstart for one happy-path outcome
• guide for a recommended workflow
• reference for inputs, outputs, and failure cases
• concept for the mental model behind the behavior
• connector, dashboard, migration, and operations when those are the real user job

If a page needs a generic ten-section template to feel “complete,” it probably is not ready.

Validation

Run these before you ship:

npm run docs:clean
npm run docs:validate

docs:clean is for hygiene.

docs:validate is the release gate.

Review bar

Reviewers should check:

• does the page help the right reader do one thing?
• are routes, tool names, and UI descriptions current?
• is the structure appropriate for the page type?
• is anything here internal-only and therefore not suitable for public docs?

Slug policy

Preserve public slugs whenever possible. If you truly need to replace a slug, coordinate the redirect as part of the same change instead of leaving the migration for later.

Next step

If you are changing editorial standards or docs release rules, read docs quality and release process. If you are rewriting a public page, start from introduction and compare the page you are editing against the current first-time-adopter voice.