Claude cho Engineering: Viết documentation chuyên nghiệp

Code tốt không có documentation vẫn là code khó bảo trì. Một README rõ ràng, runbook đầy đủ, hay API docs chính xác có thể tiết kiệm hàng giờ onboarding và debug cho cả team. Claude có thể giúp bạn viết documentation chuyên nghiệp nhanh hơn, với cấu trúc rõ ràng và phù hợp với từng đối tượng đọc.

Năm loại documentation phổ biến

1. README

Cửa ngõ đầu tiên cho bất kỳ repository nào:

• Dự án này là gì và tại sao tồn tại
• Quick start (dưới 5 phút đến lần chạy đầu tiên)
• Configuration và usage
• Contributing guide

2. API Documentation

• Endpoint reference với request/response examples
• Authentication và error codes
• Rate limits và pagination
• SDK examples

3. Runbook

• Khi nào dùng runbook này
• Prerequisites và quyền truy cập cần thiết
• Step-by-step procedure
• Rollback steps
• Escalation path

4. Architecture Document

• Context và mục tiêu
• High-level design với diagrams
• Key decisions và trade-offs
• Data flow và integration points

5. Onboarding Guide

• Environment setup
• Key systems và cách chúng kết nối
• Common tasks với walkthroughs
• Hỏi ai về vấn đề gì

Nguyên tắc viết documentation tốt

1. Viết cho người đọc: Ai sẽ đọc tài liệu này và họ cần gì?
2. Thông tin quan trọng lên đầu: Đừng chôn thông tin thiết yếu ở cuối.
3. Show, đừng chỉ tell: Code examples, commands, screenshots.
4. Giữ up-to-date: Documentation cũ còn tệ hơn không có documentation.
5. Link, không duplicate: Reference tài liệu khác thay vì copy.

Prompt mẫu: Tạo README

Viết README cho package npm của tôi:

Tên: @company/vn-phone-validator
Mục đích: Validate số điện thoại Việt Nam (Viettel, Vinaphone, Mobifone)
Tech: TypeScript, không có dependencies
Features:
- Validate format (10 số, bắt đầu bằng 0)
- Xác định nhà mạng từ prefix
- Normalize format (0xxx -> +84xxx)
- Hỗ trợ cả format cũ (11 số) để backward compat

Audience: JavaScript/TypeScript developers
Cần: Installation, quick example, full API reference, contributing guide

Prompt mẫu: Viết API Documentation

Viết API documentation cho các endpoints sau
của hệ thống quản lý nhân sự:

POST /api/employees
  Body: { name, email, department, startDate }
  Returns: Employee object với id
  Errors: 400 (validation), 409 (email duplicate), 500

GET /api/employees/:id
  Returns: Full employee profile
  Errors: 404 (not found), 403 (unauthorized)

PUT /api/employees/:id
  Body: Partial employee object (patch)
  Returns: Updated employee
  Notes: Chỉ HR admin mới update department

DELETE /api/employees/:id
  Soft delete, không xóa thật
  Returns: 204 No Content

Auth: Bearer JWT token
Rate limit: 100 req/min per user

Format: OpenAPI 3.0 style, bao gồm curl examples

Ví dụ kết quả: README từ Claude

# @company/vn-phone-validator

Validate và normalize số điện thoại Việt Nam.
Hỗ trợ tất cả nhà mạng và tự động nhận diện carrier.

## Cài đặt

npm install @company/vn-phone-validator

## Sử dụng nhanh

const { validate, getCarrier, normalize } = require('@company/vn-phone-validator');

// Validate
validate('0912345678')   // true
validate('0123456789')   // false (prefix không hợp lệ)

// Nhận diện nhà mạng
getCarrier('0912345678')  // 'Mobifone'
getCarrier('0974123456')  // 'Viettel'

// Normalize
normalize('0912345678')   // '+84912345678'
normalize('+84912345678') // '+84912345678' (idempotent)

## API Reference
...

## Contributing
...

Prompt mẫu: Viết Runbook

Viết runbook cho tình huống: Redis cache bị đầy
và service notification bắt đầu fail.

Service: notification-service (Node.js)
Infrastructure: Redis 6.0 trên AWS ElastiCache
Monitoring: CloudWatch alerts

Tình huống: CloudWatch alert "Redis Memory > 90%"
Ảnh hưởng: Push notifications chậm hoặc fail

Cần runbook với:
1. Cách verify vấn đề
2. Immediate mitigation (không cần restart)
3. Permanent fix
4. Rollback nếu action gây thêm vấn đề
5. Escalation nếu không tự xử lý được

Người dùng runbook: On-call engineer,
có thể không quen sâu với Redis.

Prompt mẫu: Onboarding Guide

Viết onboarding guide cho backend developer mới
join team của chúng tôi.

Tech stack:
- Node.js 20, TypeScript
- PostgreSQL 15 + Redis
- Docker + Docker Compose cho local dev
- GitHub + GitHub Actions CI/CD
- AWS (ECS, RDS, ElastiCache)
- Datadog cho monitoring

Cần cover:
1. Setup môi trường local (từ zero đến chạy được)
2. Cấu trúc codebase và conventions
3. Workflow hàng ngày (branch, PR, review, merge)
4. Cách chạy tests
5. Cách debug và xem logs
6. Ai hỏi về gì (Slack channels, team contacts)

Target: Developer mới, biết Node.js nhưng
chưa biết gì về codebase chúng tôi.

Biến code thành documentation

Claude cũng có thể đọc code và tự động tạo documentation:

Đây là TypeScript function phức tạp.
Hãy viết JSDoc documentation cho nó,
bao gồm description, @param, @returns,
@throws, và @example:

async function processVietnamPayment(
  amount: number,
  method: 'momo' | 'vnpay' | 'banking',
  customerId: string,
  metadata?: Record<string, unknown>
): Promise<PaymentResult> {
  // [code implementation]
}

Documentation cho Vietnamese tech context

Khi viết documentation cho sản phẩm Việt Nam, có một số điểm cần lưu ý:

Viết README cho SDK tích hợp thanh toán Việt Nam
(MoMo, VNPay, ZaloPay).

Lưu ý đặc thù:
- Môi trường sandbox và production có URL khác nhau
- Cần giải thích về checksum/signature verification
  vì đây là yêu cầu bắt buộc của các cổng thanh toán VN
- Các developers VN thường quen với PHP/Java,
  hãy include examples cho cả Node.js và Python
- Documentation cần có cả tiếng Việt và tiếng Anh

Mẹo viết documentation với Claude

• Chỉ định audience rõ ràng: "Viết cho developer mới, chưa biết AWS" khác với "Viết cho senior DevOps engineer".
• Cung cấp context về codebase: Càng nhiều context về tech stack và conventions, documentation càng chính xác.
• Yêu cầu format cụ thể: "Markdown", "OpenAPI 3.0", hoặc "Confluence wiki format".
• Review và bổ sung: Claude tạo khung tốt nhưng bạn cần thêm context nội bộ như tên system, URL thực, credentials placeholder.

Bước tiếp theo

Documentation tốt là nền tảng của engineering team hiệu quả:

• Thư viện ứng dụng Claude cho Engineering
• Kết hợp với Architecture workflow để document các quyết định thiết kế quan trọng
• Dùng Runbook workflow trong Incident Response khi có sự cố production

Bài viết liên quan

• Claude cho Engineering: Chiến lược testing toàn diện
• Claude cho Engineering: Debug và xử lý lỗi
• Claude cho Engineering: Deploy checklist tự động
• Best Practices cho Vision — Tối ưu hình ảnh gửi Claude
• Claude cho Data: Validation và data quality