tech-writing

name	tech-writing
version	1.0.0
description	Technical writing and documentation skill — specs, runbooks, changelogs, meeting notes, ADRs
requires	[]
task_types	["docs","documentation","tech-writing","spec","changelog","runbook"]
applies_to_tags	["docs","documentation","spec","changelog","runbook","adr","meeting-notes"]

Technical Writing Skill

Nguyên tắc cốt lõi

• Viết cho người đọc chưa biết gì về context
• Mỗi đoạn trả lời một câu hỏi cụ thể
• Code examples phải chạy được ngay, không phải pseudocode
• Cấu trúc theo nhu cầu đọc: từ overview → detail, không ngược lại
• Ngắn gọn hơn luôn tốt hơn — không thêm từ để "có vẻ đầy đủ"

Loại tài liệu và template

1. Technical Spec / PRD

# Feature: [Tên feature]

## Problem
[Vấn đề hiện tại là gì? Ai bị ảnh hưởng?]

## Proposed Solution
[Giải pháp đề xuất — 1-3 câu]

## Requirements
### Must Have
- [ ] ...
### Nice to Have
- [ ] ...

## Design / Architecture
[Sơ đồ hoặc mô tả data flow, API contract]

## Out of Scope
[Cái gì KHÔNG nằm trong feature này]

## Open Questions
- [ ] Question 1 → [assigned to] [deadline]

2. API Documentation

## POST /api/vault/tasks

Tạo task mới trong vault.

**Request Body**
| Field | Type | Required | Description |
|---|---|---|---|
| title | string | ✓ | Tiêu đề task |
| column | string | ✓ | `todo` / `in-progress` / `review` / `done` |
| priority | string | | `critical` / `high` / `medium` / `low` |

**Response 201**
```json
{ "data": { "id": "task-abc123", "title": "...", "status": "todo" } }

Errors

• 400 — Missing required fields
• 409 — Task with same title exists in column

### 3. Runbook

```markdown
# Runbook: [Tên sự cố / procedure]

## Trigger
[Khi nào dùng runbook này]

## Impact
[Ảnh hưởng tới gì nếu không xử lý]

## Steps
1. [Bước cụ thể với lệnh exact]
   ```bash
   pm2 restart relayhq-api

2. [Verify bằng cách nào]

   curl http://localhost:44210/api/health
   

Rollback

[Cách undo nếu cần]

Escalation

[Khi nào cần leo thang, ai là người tiếp nhận]

### 4. Architecture Decision Record (ADR)

```markdown
# ADR-NNN: [Tiêu đề quyết định]

**Date:** YYYY-MM-DD  
**Status:** Proposed / Accepted / Deprecated

## Context
[Tình huống đặt ra vấn đề — facts, không opinion]

## Decision
[Quyết định cụ thể đã chọn]

## Rationale
[Tại sao chọn option này — trade-offs được acknowledge]

## Alternatives Considered
- **Option A**: [mô tả] — rejected vì [reason]
- **Option B**: [mô tả] — rejected vì [reason]

## Consequences
- Positive: ...
- Negative: ...
- Neutral: ...

5. Meeting Notes / Sprint Summary

# [Meeting type] — YYYY-MM-DD

**Attendees:** @alice, @bob, @claude-code  
**Duration:** 30 min

## Decisions Made
- [Decision với context ngắn]

## Action Items
| Task | Owner | Due |
|---|---|---|
| Implement X | @alice | 2026-05-01 |
| Review PR #123 | @bob | EOD |

## Parking Lot
[Vấn đề chưa giải quyết, cần follow-up]

6. Changelog / Release Notes

## [1.2.0] — YYYY-MM-DD

### Added
- Agent auto-launch khi task được assign
- Visual sprite cho agent trong DesktopView

### Changed
- Claim API nay trả về full task object thay vì chỉ ID

### Fixed
- Race condition khi 2 agents claim cùng lúc

### Removed
- Legacy `/api/v1/assign` endpoint (deprecated từ 1.0.0)

Quality Checklist

• Title đủ mô tả không cần đọc body
• Không có jargon chưa được giải thích
• Code examples đã được test chạy được
• Links trỏ đến đúng file/URL
• Không có TODO chưa resolved trong docs published
• Ngày tháng và version numbers chính xác
• Cross-reference với docs liên quan

Những lỗi thường gặp

• Viết WHAT code làm thay vì WHY thiết kế như vậy
• Dùng "simply", "just", "obviously" — người đọc không thấy đơn giản đâu
• Docs chỉ update khi có incident — cần update cùng với code change
• Thiếu ví dụ cụ thể — abstract description không đủ
• Quá dài — nếu đọc mất hơn 5 phút thì chia nhỏ