Quy chuẩn viết docs

Mục tiêu

Giữ CenterOS Docs ngắn, đúng implementation, dễ review và dùng được khi engineer cần build, validate hoặc debug.

Section ownership

• architecture: system model, service boundary, token/context model, runtime rule cấp hệ thống.
• services: runtime, API surface, behavior và ownership của từng service.
• flows: luồng FE-BE hoặc service-to-service theo journey kỹ thuật.
• use-cases: một endpoint hoặc một use case cụ thể, input/output/rule chính.
• database: schema/table ownership, migration note, cross-service database rule.
• runbooks: thao tác validate/debug/deploy/reset có thể chạy được.
• reference: glossary, conventions, headers, token scopes, env var names.
• adr: quyết định kiến trúc đã chọn, context ngắn, consequence.

DOD cho một file

• File trả lời một câu hỏi rõ ràng.
• Không viết dài lan man.
• Không invent implementation.
• Fact đã đóng được nói rõ là đã đóng.
• Fact chưa validate được đánh dấu TODO hoặc Chưa đóng.
• Không chứa secrets, token thật, credential hoặc giá trị private từ .env.
• Giữ nguyên identifiers: API paths, header names, JSON fields, Docker names, image names, env var names, schema/table names.
• Có related links khi giúp người đọc đi tiếp.

DOD cho một batch

• Sidebar order hợp lý.
• Không có empty files.
• Không có docs toàn TODO.
• Không mâu thuẫn giữa các file.
• bun run types:check pass.
• bun run lint pass.
• bun run build pass.

Templates

Architecture doc:

---
title: ...
description: ...
---

# ...

## Mục tiêu
## Trạng thái hiện tại
## Luồng chính
## Quy tắc quan trọng
## Liên quan
## TODO

Service doc:

# Service name

## Mục tiêu
## Runtime
## API surface
## Ownership
## Không sở hữu
## TODO

Flow doc:

# Flow name

## Mục tiêu
## Actors
## Luồng chính
## Failure cases
## Validated
## TODO

Use case doc:

# Use case name

## Endpoint
## Mục tiêu
## Request
## Response
## Rules
## TODO

Database doc:

# Database topic

## Mục tiêu
## Owner service
## Tables/schema
## Read/write rules
## Migration notes
## TODO

Runbook doc:

# Runbook name

## Mục tiêu
## Prerequisites
## Commands
## Expected result
## Debug notes
## TODO