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

trigger

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)

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

# 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

# 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

Development / Phát Triển

[Development instructions...]

Testing / Kiểm Thử

pnpm test

Deployment / Triển Khai

See Deployment Guide

### 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
• External Link

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

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

# 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

# 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

# H1: Document Title (only one per file)
## H2: Major Sections
### H3: Subsections
#### H4: Details (use sparingly)

Bilingual Patterns

# 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 structure and standards
• Comment Code - Code commenting standards
• API Design - API documentation
• Testing Patterns - Test documentation