pos-system/.agent/rules/documentation.md

---
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