Docs Quality and Release Process

This page is for maintainers and contributors working on the RetainDB docs set.

The goal is not to maximize page count or structural consistency. The goal is to help a first-time adopter get to a correct result quickly.

Editorial rules

Every page should be written for a developer discovering RetainDB, not for the engineer who already knows the system.

That means:

• open with outcome, not taxonomy
• answer the first likely question in the first screenful
• use one primary job per page
• choose structure based on page_type, not habit
• cut sections that do not help the reader make progress

The page types

Use the smallest page shape that fits the job:

• quickstart
• guide
• reference
• concept
• tutorial
• connector
• dashboard
• migration
• operations

If a page only works because it inherits a generic ten-section shell, it is probably not finished.

Frontmatter rules

Public docs pages should include:

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

Optional fields are only useful when they add meaning:

• version_track
• applies_to
• availability
• hide_feedback

applies_to should not be used as filler. If it does not communicate a real compatibility distinction, leave it out.

Availability and feedback policy

Use availability to control what should be public:

• ga
• beta
• hidden

Use quality_tier and hide_feedback to control feedback collection.

The helpfulness widget should only appear on complete public pages. Do not ask for feedback on placeholders, drafts, or hidden docs.

Authoring workflow

When you update docs:

1. decide whether the page should exist as a standalone page
2. choose the correct page_type
3. rewrite for the reader's job, not the template
4. verify examples against real routes, tools, or UI
5. validate the docs corpus before shipping

Mechanical cleanup

Do not spend editorial energy on hygiene tasks that can be scripted.

Use the cleanup script for things like:

• encoding cleanup
• heading normalization
• broken boilerplate removal
• stale formatting fixes

Current commands:

npm run docs:clean
npm run docs:validate

What reviewers should look for

A docs review is not a copyedit only. Reviewers should check:

• does the page help the right reader do one clear thing?
• are the routes, tool names, and examples real?
• is the structure earning its length?
• are warnings actually warnings?
• are internal QA concepts leaking into public docs?

Release bar

A docs page is ready to ship when:

• the page has a clear audience and job
• code examples are aligned with the current implementation
• the page does not rely on generic placeholder sections
• validation passes
• the page is strong enough that a feedback widget would be reasonable

Next step

If you are adding or rewriting a public page, read contributing next. If you are changing the public docs experience itself, inspect mint.json and the docs app renderer in the frontend codebase before shipping.