--- trigger: always_on --- # Documentation Writing Guidelines ## Documentation Structure ``` docs/ ├── en/ # English documentation │ ├── guides/ # How-to guides │ │ ├── getting-started.md │ │ ├── development.md │ │ ├── deployment.md │ │ └── local-development.md │ ├── architecture/ # System design docs │ │ ├── system-design.md │ │ └── service-communication.md │ ├── api/ # API documentation │ │ └── openapi/ │ └── runbooks/ # Operational guides │ ├── incident-response.md │ └── rollback-procedure.md ├── vi/ # Vietnamese documentation (mirror structure) └── README.md # Documentation index ``` ## Where to Put Documentation ### Project-Level Documentation - **Location**: `docs/en/` and `docs/vi/` - **Examples**: Getting started, deployment guides, architecture - **Format**: Markdown with bilingual support ### Service/Package Documentation - **Location**: `services/[service-name]/README.md` or `packages/[package-name]/README.md` - **Content**: Service-specific setup, API endpoints, configuration - **Format**: Single README with bilingual sections ### Deployment Documentation - **Location**: `deployments/[environment]/README.md` - **Content**: Environment-specific deployment instructions - **Format**: Technical, operations-focused ### Infrastructure Documentation - **Location**: `infra/[component]/README.md` - **Content**: Infrastructure component configuration and usage - **Examples**: `infra/traefik/README.md`, `infra/observability/README.md` ## Bilingual Documentation Rules ### Format Options **Option 1: Side-by-side (Recommended for short content)** ```markdown # Service Name / Tên Dịch Vụ This is a description. Đây là mô tả. ``` **Option 2: Separate files (Recommended for long content)** ``` docs/ ├── en/ │ └── guides/ │ └── deployment.md └── vi/ └── guides/ └── deployment.md ``` **Option 3: Sections (For mixed content)** ```markdown # English Section Content in English... --- # Phần Tiếng Việt Nội dung bằng tiếng Việt... ``` ### When to Use Each Format - **Side-by-side**: README files, short guides, configuration docs - **Separate files**: Long guides (>200 lines), architecture docs, runbooks - **Sections**: API documentation, technical specifications ## Documentation Templates ### Service README Template ```markdown # Service Name / Tên Dịch Vụ > **EN**: Brief description in English > **VI**: Mô tả ngắn gọn bằng tiếng Việt ## Features / Tính Năng - Feature 1 / Tính năng 1 - Feature 2 / Tính năng 2 ## Prerequisites / Yêu Cầu - Node.js 20+ - PostgreSQL (Neon) - Redis ## Quick Start / Bắt Đầu Nhanh ```bash # Install dependencies / Cài đặt dependencies pnpm install # Setup environment / Thiết lập môi trường cp .env.example .env # Start service / Khởi động service pnpm dev ``` ## Configuration / Cấu Hình | Variable | Description / Mô Tả | Default | Required | |----------|---------------------|---------|----------| | PORT | Server port / Cổng server | 5000 | No | ## API Endpoints See [API Documentation](../../docs/api/openapi/service-name.yaml) ## Development / Phát Triển [Development instructions...] ## Testing / Kiểm Thử ```bash pnpm test ``` ## Deployment / Triển Khai See [Deployment Guide](../../docs/en/guides/deployment.md) ``` ### Guide Template (docs/en/guides/) ```markdown # Guide Title **Last Updated**: 2024-01-01 **Difficulty**: Beginner/Intermediate/Advanced ## Overview Brief overview of what this guide covers. ## Prerequisites - Requirement 1 - Requirement 2 ## Step-by-Step Instructions ### Step 1: Title Description and commands... ```bash command here ``` ### Step 2: Title Description and commands... ## Troubleshooting ### Issue 1 **Problem**: Description **Solution**: Steps to fix ## Next Steps - Link to related guide - Link to another resource ## Resources - [Related Doc](../path/to/doc.md) - [External Link](https://example.com) ``` ### Architecture Document Template ```markdown # Component Architecture ## Overview High-level description of the component. ## Architecture Diagram ```mermaid graph TD A[Component A] --> B[Component B] B --> C[Component C] ``` ## Components ### Component Name **Purpose**: What it does **Technology**: Tech stack **Dependencies**: What it depends on ## Data Flow 1. Step 1 2. Step 2 3. Step 3 ## Design Decisions ### Decision 1 **Context**: Why this decision was needed **Decision**: What was decided **Consequences**: Impact of the decision ## Deployment How this component is deployed. ## Monitoring How to monitor this component. ``` ## Writing Style Guidelines ### Technical Writing Principles 1. **Clear and Concise**: Use simple language, avoid jargon 2. **Action-Oriented**: Start with verbs (Install, Configure, Deploy) 3. **Structured**: Use headings, lists, and tables 4. **Examples**: Provide code examples and commands 5. **Visual**: Use diagrams where helpful ### Code Examples ```markdown # Good: With context and explanation Install dependencies using pnpm: ```bash pnpm install ``` # Bad: No context ```bash pnpm install ``` ``` ### Commands - Always show the full command - Include comments for clarity - Show expected output when helpful ```bash # Good docker-compose up -d # Expected output: Creating network, Starting containers... # Bad docker-compose up ``` ### Links - Use relative links for internal docs - Use descriptive link text (not "click here") ```markdown # Good See the [Deployment Guide](../guides/deployment.md) for details. # Bad Click [here](../guides/deployment.md) for more info. ``` ## Documentation Checklist ### Before Writing - [ ] Determine correct location (docs/ vs service README) - [ ] Choose bilingual format (side-by-side vs separate) - [ ] Review existing docs for consistency ### While Writing - [ ] Use clear, concise language - [ ] Include code examples - [ ] Add diagrams where helpful - [ ] Provide troubleshooting section - [ ] Link to related documentation ### After Writing - [ ] Test all commands and code examples - [ ] Check all links work - [ ] Ensure bilingual consistency - [ ] Update documentation index (docs/README.md) - [ ] Request review from team ## Common Mistakes to Avoid ### ❌ Don't - Write documentation in only one language - Put detailed guides in service README (use docs/) - Use absolute paths in links - Assume prior knowledge - Skip code examples - Forget to update when code changes ### ✅ Do - Maintain bilingual documentation - Use appropriate location (docs/ vs README) - Use relative links - Explain prerequisites - Provide working examples - Keep docs up-to-date with code ## Documentation Maintenance ### When to Update Documentation - New feature added - API changes - Configuration changes - Deployment process changes - Bug fixes affecting usage - Architecture changes ### Version Documentation For major changes, consider: - Adding "Last Updated" date - Creating versioned docs (v1/, v2/) - Maintaining changelog ## Tools and Resources ### Markdown Tools - **Mermaid**: For diagrams - **Tables Generator**: For complex tables - **Markdown Linter**: For consistency ### Documentation Testing ```bash # Check for broken links find docs -name "*.md" -exec markdown-link-check {} \; # Lint markdown files markdownlint docs/**/*.md ``` ## Examples from Project ### Good Documentation Examples - `docs/en/guides/getting-started.md` - Clear step-by-step guide - `services/_template/README.md` - Comprehensive service README - `deployments/local/README.md` - Operations-focused deployment guide ### Documentation Locations Reference | Content Type | Location | Format | |--------------|----------|--------| | Getting Started | `docs/en/guides/getting-started.md` | Separate files | | Service Setup | `services/[name]/README.md` | Side-by-side | | Deployment | `docs/en/guides/deployment.md` | Separate files | | Architecture | `docs/en/architecture/` | Separate files | | API Specs | `docs/en/api/openapi/` | OpenAPI YAML | | Runbooks | `docs/en/runbooks/` | Separate files | | Infrastructure | `infra/[component]/README.md` | Side-by-side | | Environment Config | `deployments/[env]/README.md` | Technical only | ## Quick Reference ### File Naming - Use kebab-case: `getting-started.md` - Be descriptive: `local-development.md` not `dev.md` - Match EN and VI filenames ### Heading Levels ```markdown # H1: Document Title (only one per file) ## H2: Major Sections ### H3: Subsections #### H4: Details (use sparingly) ``` ### Bilingual Patterns ```markdown # Pattern 1: Inline Description / Mô tả # Pattern 2: After slash PORT=5000 # Server port / Cổng server # Pattern 3: Table | Variable | Description / Mô Tả | # Pattern 4: Code comments # EN: Install dependencies # VI: Cài đặt dependencies pnpm install ``` ## Resources - [Project Rules](../project-rules/SKILL.md) - Project structure and standards - [Comment Code](../comment-code/SKILL.md) - Code commenting standards - [API Design](../api-design/SKILL.md) - API documentation - [Testing Patterns](../testing-patterns/SKILL.md) - Test documentation