Documentation Style Guide

SyncTV docs are organized by reader task. Before writing, decide who the reader is, what they need to finish, and how they can verify the result. Do not mix concepts, step-by-step procedures, field references, and troubleshooting matrices in one page.

Page Types

Type	Purpose	Write it as
Task	Help a reader complete one action	Prerequisites, steps, validation, failure handling
Concept	Explain a product model or system responsibility	Objects, relationships, responsibilities, and next steps
Reference	Look up fields, commands, metrics, or errors	Stable, searchable structure; no teaching burden
Troubleshooting	Diagnose by symptom	Symptom, check first, owner, next step
Runbook	Admin or operator procedure	Impact, operation order, rollback, validation

Opening Paragraph

Start by saying what the page helps the reader do. Avoid generic background.

Use:

This page explains how to create a room, configure join rules, and verify access with a normal member account.

Avoid:

This section provides a comprehensive overview of room capabilities and complex boundaries.

Titles

• Task pages use actions: Create and Join Rooms, Add Media.
• Concept pages use nouns: Playback Model, Permissions Model.
• Reference pages name the object: Runtime Settings Reference, Metrics Catalog.
• Do not use vague labels such as “complete guide” or “best practices”.

Wording

Prefer short sentences and concrete actions.

Avoid overusing	Prefer
should normally confirm	check
Related Pages	Next steps, Reference, Continue troubleshooting
semantics	meaning, impact, rule
boundary	responsibility, scope, limitation
production rules	before production, operation rules

These words are not banned. Configuration, security, and architecture pages may need them. Do not use them as a page template.

Links

• Put links where the reader needs the next step.
• Task pages should end with “Next steps”, not a generic link pile.
• Reference pages can keep reference links, but each link should have a clear purpose.
• Do not use old deployment/ or guides/ routes.
• Avoid fragile anchor links into long pages; prefer links to dedicated pages.

Terminology

Concept	Chinese	English
Provider	Provider or 媒体源 Provider	Provider
Realtime	Realtime or 实时连接	Realtime
runtime settings	runtime settings or 运行设置	runtime settings
management gRPC	management gRPC or 管理控制面	management gRPC
proxy slice cache	proxy slice cache	proxy slice cache

Define a term on first use, then keep the same name in that page.

Locale Mirrors

Every Chinese page must have an English mirror under en/ with the same path. English pages should be rewritten for English product docs, not translated sentence by sentence.

• Use short sentences.
• Use action titles or clear nouns.
• Avoid abstract nouns when a concrete action works.
• Keep product names stable across locales.

Validation

Run before submitting docs:

cd docs
npm run validate

Validation checks internal links, Starlight icons, removed routes, retired titles, unfinished-work markers, and English mirrors. Generic related-page endings are reported as warnings and should be cleaned up over time.