Getting Started Guide — Documentation Skills Toolkit

Hướng dẫn chi tiết cho team member lần đầu sử dụng bộ toolkit. Đọc guide này trong ~15 phút, bạn sẽ hiểu toolkit hoạt động thế nào và viết được doc đầu tiên.

1. Toolkit này là gì?

Documentation Skills Toolkit là bộ công cụ chuẩn hóa cách viết technical documentation cho team. Thay vì mỗi người viết docs theo cách riêng, toolkit cung cấp:

Skills — Bộ quy tắc hướng dẫn cách viết từng loại doc (runbook, guide, training...)
Templates — File mẫu copy-paste, chỉ cần điền nội dung
Tools — CLI tạo doc tự động, lint kiểm tra format, validator kiểm tra cấu trúc
Pipeline — Quy trình Docs-as-Code: Write → Lint → Review → Publish → Audit

Tại sao cần toolkit?

TRƯỚC (không có toolkit):
  - Docs rải rác trên Wiki, Drive, Confluence
  - Format không thống nhất, mỗi người viết 1 kiểu
  - Runbook chỉ có text mô tả, không chạy được
  - Docs cũ 6 tháng không ai update
  - Người mới vào team không biết docs ở đâu

SAU (có toolkit):
  - Docs tập trung trong Git repo, quản lý như code
  - Format thống nhất nhờ markdownlint tự động kiểm tra
  - Runbook có commands copy-paste + expected output
  - Quarterly audit phát hiện docs cũ
  - MkDocs site searchable, navigable, auto-deploy

2. Concept chính

Skills = "Cách viết"

Mỗi skill là một file .md chứa bộ quy tắc cho 1 loại documentation:

Skill	Viết cái gì	File
Docs Engineer	Setup MkDocs, chuẩn Markdown, cấu trúc thư mục	`skills/docs-engineer.md`
Ops Runbook Writer	Runbook vận hành, network docs, incident docs	`skills/ops-runbook-writer.md`
Training Doc Writer	Training, onboarding, curriculum, learning path	`skills/training-doc-writer.md`
Project Doc Writer	ADR, tech spec, how-to guide, quick reference	`skills/project-doc-writer.md`
Infra Security Doc	Security policy, RBAC, audit log, vulnerability	`skills/infra-security-doc.md`

Mỗi skill có cấu trúc giống nhau:

Skill
├── Context          — Mô tả scope, khi nào dùng
├── Iron Law         — 1 quy tắc KHÔNG BAO GIỜ vi phạm
├── Guardrails       — Checklist kiểm tra TRƯỚC khi viết
├── Decision Tree    — Flowchart chọn đúng skill
├── Content          — Hướng dẫn chi tiết + ví dụ good/bad
├── Red Flags        — Dấu hiệu cần DỪNG LẠI
├── Remember         — Bảng tóm tắt rules nhanh
└── Related Skills   — Link tới skills liên quan

Bạn không cần đọc hết skill. Chỉ cần đọc Iron Law (1 câu) và Guardrails (3-5 checkboxes) là đủ để bắt đầu.

Prompts = "Prompt cho AI"

13 prompt templates trong prompts/ giúp AI agent tạo doc đúng chuẩn. Hoạt động với mọi AI agent (Claude, ChatGPT, Antigravity, Copilot...):

Khi bạn cần...	Dùng prompt	AI sẽ đọc skill + template
Tạo runbook	create-runbook.md	ops-runbook-writer + T1
Tạo ADR	create-adr.md	project-doc-writer + T2/T9/T10
Viết how-to guide	create-howto.md	project-doc-writer + T3
Tạo training module	create-training.md	training-doc-writer + T4
Không biết dùng gì	select-skill.md	Tất cả skills
Review doc	review-doc.md	doc-quality-scorecard

Xem danh sách đầy đủ: prompts/README.md

Templates = "File mẫu"

11 templates (T1-T11) là file mẫu copy-paste sẵn. Mỗi template map tới 1 use case:

Khi bạn cần...	Dùng template	CLI command
Viết SOP vận hành server/service	T1 Runbook	`docs-toolkit new runbook "Tên"`
Ghi nhận quyết định architecture	T2 ADR	`docs-toolkit new adr "Tên"`
Hướng dẫn step-by-step	T3 How-to Guide	`docs-toolkit new howto "Tên"`
Tạo module training nội bộ	T4 Training	`docs-toolkit new training "Tên"`
Document hạ tầng mạng	T5 Network	`docs-toolkit new network "Tên"`
Phân tích sau sự cố	T6 Postmortem	`docs-toolkit new postmortem "Tên"`
Lên kế hoạch bảo trì	T7 Maintenance	`docs-toolkit new maintenance "Tên"`
Tóm tắt version release	T8 Release Notes	`docs-toolkit new release-notes "vX.Y"`
Complex architecture decision	T9 ADR (MADR)	`docs-toolkit new adr-madr "Decision"`
Quick decision, POC	T10 ADR (Lightweight)	Copy `templates/adr-lightweight.md`
Kiểm tra kiến thức	T11 Knowledge Check	`docs-toolkit new knowledge-check "Topic"`

Pipeline = "Quy trình"

Docs-as-Code = quản lý docs giống source code:

Write → Lint → Review → Publish → Audit
  │       │       │        │        │
  │       │       │        │        └─ Mỗi quý: tìm docs cũ > 90 ngày
  │       │       │        └─ mkdocs gh-deploy (GitHub Pages)
  │       │       └─ Pull Request + peer review
  │       └─ markdownlint + cspell tự động (pre-commit hook)
  └─ Chọn skill → copy template → viết nội dung

3. Setup (lần đầu)

Prerequisites

Trước khi bắt đầu, đảm bảo đã cài:

Tool	Kiểm tra	Cài đặt (Ubuntu/WSL)	Cài đặt (macOS)
Python 3.8+	`python3 --version`	`sudo apt update && sudo apt install python3 python3-pip`	`brew install python3`
Node.js 18+	`node --version`	nvm hoặc `sudo apt install nodejs npm`	`brew install node`
Git	`git --version`	`sudo apt install git`	`brew install git`

Ubuntu/Debian: Luôn chạy sudo apt update trước khi cài đặt packages để đảm bảo package index mới nhất.

Bước 1: Clone và cài đặt

git clone https://github.com/lampd-2157/documentation-skills-toolkit.git
cd documentation-skills-toolkit
bash scripts/setup.sh

Script sẽ tự động cài:

MkDocs + Material theme + plugins
markdownlint-cli2 (lint markdown)
Pre-commit hooks (tự lint khi commit)
VS Code snippets (gõ doc- → autocomplete)
cspell + link-check configs

Bước 2: Xem demo site

pip install -r demo-site/requirements.txt
make serve
# Mở http://localhost:8000

Demo site có ví dụ thực tế cho các templates — xem để biết output mong đợi.

Bước 3: Áp dụng vào dự án của bạn

# Trong dự án của bạn
cd /path/to/your-project

# Copy configs
cp /path/to/toolkit/examples/mkdocs-starter.yml mkdocs.yml
cp /path/to/toolkit/config/.markdownlint.json .markdownlint.json
cp /path/to/toolkit/config/pre-commit.yaml .pre-commit-config.yaml

# Setup
pip install -r /path/to/toolkit/config/requirements.txt
pre-commit install

# Tạo cấu trúc docs
mkdir -p docs/{getting-started,operations/runbooks,development/adr,guides/how-to,training,assets/images}
echo "# Project Documentation" > docs/index.md

# Verify
mkdocs serve

4. Viết doc đầu tiên

Cách 1: Dùng AI Agent (Recommended)

Mở prompts/create-runbook.md
Copy phần Prompt, paste vào AI agent (Claude, ChatGPT, Antigravity, Copilot...)
Sửa đoạn có dấu <<<< SỬA ... >>>> bằng thông tin thực tế (ví dụ: "Nginx Load Balancer trên Ubuntu 22.04")
AI tạo doc → bạn review và chỉnh sửa thông tin kỹ thuật
Validate: make lint
Commit + PR

Cách 2: Viết thủ công

Bước 1: Tạo file từ template

./scripts/docs-toolkit new runbook "Nginx Load Balancer"
# → Created: docs/operations/runbooks/nginx-load-balancer-runbook.md

Bước 2: Mở skill để biết quy tắc

Mở skills/ops-runbook-writer.md, đọc:

Iron Law: "Every runbook MUST have copy-paste commands AND expected output"
Guardrails: Test commands, contact info up-to-date, severity defined, backup procedure

Bước 3: Điền nội dung

Mở file vừa tạo, điền các placeholder [...]. Quan trọng nhất:

## Health Checks
| Check        | Command                          | Expected       |
| ------------ | -------------------------------- | -------------- |
| Nginx alive  | `curl -s localhost/health`       | `200 OK`       |
| Config valid | `sudo nginx -t`                 | `syntax is ok` |

## Troubleshooting
### 502 Bad Gateway
**Symptoms:** Browser hiển thị 502
**Root Cause:** Backend server down
**Fix:**
1. `sudo systemctl status myapp` — check backend
2. `sudo systemctl restart myapp` — restart nếu inactive
3. `curl -s localhost:8080/health` — verify backend up
**Prevention:** Setup health check monitoring

Bước 4: Verify

# Lint
npx markdownlint-cli2 docs/operations/runbooks/nginx-load-balancer-runbook.md

# Preview
make serve
# → Mở localhost:8000, navigate tới runbook, kiểm tra render

Bước 5: Commit & PR

git add docs/operations/runbooks/nginx-load-balancer-runbook.md
git commit -m "docs: add Nginx LB runbook"
git push && gh pr create

5. Chọn đúng skill / template

Flowchart

Bạn cần viết gì?
  │
  ├── Liên quan đến VẬN HÀNH hệ thống?
  │     ├── SOP / runbook cho service?           → T1 Runbook
  │     ├── Document network / server?           → T5 Network Topology
  │     ├── Phân tích incident đã xảy ra?        → T6 Postmortem
  │     └── Lên kế hoạch bảo trì / upgrade?     → T7 Maintenance Window
  │
  ├── Liên quan đến HƯỚNG DẪN / ĐÀO TẠO?
  │     ├── Step-by-step cho 1 task cụ thể?      → T3 How-to Guide
  │     ├── Module training cho team?             → T4 Training Module
  │     └── Cheat sheet / quick reference?       → project-doc-writer §3
  │
  ├── Liên quan đến DỰ ÁN / KIẾN TRÚC?
  │     ├── Ghi nhận quyết định architecture?    → T2 ADR
  │     ├── Technical specification?              → project-doc-writer §1.2
  │     └── Release notes cho version mới?        → T8 Release Notes
  │
  └── Không biết chọn gì?
        └── Xem docs/skill-composition-recipes.md

Ví dụ thực tế

Scenario	Template	Skill
"Setup monitoring cho production cluster"	T1 Runbook	ops-runbook-writer
"Tại sao team chọn PostgreSQL thay MongoDB"	T2 ADR	project-doc-writer
"Hướng dẫn member mới setup dev environment"	T3 How-to	project-doc-writer
"Training Git workflow cho intern"	T4 Training	training-doc-writer
"Document VLAN layout office mới"	T5 Network	ops-runbook-writer
"DB crash hôm qua, cần postmortem"	T6 Postmortem	ops-runbook-writer
"Upgrade PostgreSQL cuối tuần này"	T7 Maintenance	ops-runbook-writer
"Release v3.0 cần release notes"	T8 Release Notes	project-doc-writer

5b. Smart Routing (v5.0.0+)

Thay vì tự quyết định skill/template, bạn có thể để AI tự routing dựa trên keywords trong request.

v5.3.0: Routing nay có thêm CLI mode (docs-toolkit route) và Wizard mode (docs-toolkit wizard) — xem chi tiết tại CHANGELOG.

Cách hoạt động

User request → routing-signals.yaml → keyword match → confidence score → chọn skill

Confidence scoring:

Score	Ý nghĩa	Hành động
>= 0.8	High confidence	AI tự chọn, không hỏi
0.5 – 0.8	Medium confidence	AI gợi ý + hỏi confirm
< 0.5	Low confidence	Dùng `prompts/select-skill.md`

Keyword boost: Mỗi keyword match +0.1. Ví dụ: "runbook" + "incident" + "server" = 0.5 + 0.3 = 0.8 → auto-select ops-runbook-writer.

Composition Rules — Kết hợp nhiều skills

Khi request match nhiều skills, AI áp dụng composition rule thay vì chọn 1 skill:

Rule	Khi nào	Primary	Secondary Iron Law
How-to with commands	How-to guide có network/server commands	project-doc-writer (T3)	ops-runbook-writer
Runbook with security	Runbook cho hệ thống có security requirements	ops-runbook-writer (T1)	infra-security-doc
Training with hands-on ops	Training có lab với real infrastructure	training-doc-writer (T4)	ops-runbook-writer
Security policy + ADR	Security decision cần document dạng ADR	infra-security-doc	project-doc-writer

File config: config/routing-signals.yaml — đọc để hiểu logic chi tiết.

Phase 0 Interview (v5.0.0)

Trước khi tạo doc, AI hỏi 3 câu bắt buộc (Layer 1 Universal):

AUDIENCE — Ai đọc doc này? (role, kinh nghiệm, context)
SCOPE — Doc cover gì? Không cover gì? (tránh over-engineer)
ENVIRONMENT — OS, versions, tools cụ thể? (để examples chính xác)

File prompt: prompts/interview-before-create.md

Ví dụ: "Viết runbook cho Redis cluster" → AI hỏi:

Audience: SRE mới hay experienced? (ảnh hưởng step detail level)
Scope: Standalone hay cluster? Có Sentinel không? (ảnh hưởng commands)
Environment: Ubuntu 22.04? Redis 7.x? (ảnh hưởng package names và paths)

Template Section Tiers (v4.3.0)

Mỗi template có 3 tiers — không cần include tất cả sections:

Tier	Ý nghĩa	Bỏ qua?
required	PHẢI có — thiếu = doc incomplete	Không
recommended	NÊN có — cảnh báo nếu thiếu	Được nếu N/A
optional	CÓ THỂ thêm khi relevant	Thoải mái

Ví dụ T3 How-to: Prerequisites + Steps + Verify là required. Troubleshooting là recommended. FAQ, Rollback là optional.

6. Workflow hàng ngày

Viết doc mới

AI Agent (Recommended):

# 1. Chọn prompt từ prompts/ → copy → paste vào AI agent
# 2. AI tạo doc → review + chỉnh sửa
# 3. Validate
make lint
# 4. Commit + PR

Manual:

# 1. Tạo từ template
./scripts/docs-toolkit new <type> "<title>"
# 2. Đọc skill → điền nội dung
# 3. Validate
make lint
# 4. Commit + PR
git add path/to/your-doc.md
git commit -m "docs: add <description>"

Review doc của người khác

Dùng Quality Scorecard — chấm 10 tiêu chí, mỗi tiêu chí 0-1:

Structure — đúng template?
Commands testable — copy-paste chạy được?
Prerequisites — list đầy đủ?
Expected results — mỗi step có expected output?
Visual aids — có diagram?
Metadata — có YAML header?
Markdown quality — lint pass?
Freshness — updated gần đây?
Audience — target audience rõ ràng?
Non-author tested — người khác đọc hiểu?

Score >= 7 → approve. Score < 7 → request changes.

Quarterly audit

# Tìm docs cũ hơn 90 ngày
find docs/ -name "*.md" -mtime +90 -type f | sort

# Tìm docs vẫn còn draft
grep -rl "status: draft" docs/ | sort

7. VS Code Tips

Sau khi chạy setup.sh, gõ doc- trong VS Code sẽ hiện autocomplete cho 9 snippets:

Prefix	Snippet
`doc-header`	YAML metadata header
`doc-runbook`	T1 Runbook skeleton
`doc-adr`	T2 ADR skeleton
`doc-howto`	T3 How-to Guide skeleton
`doc-training`	T4 Training Module skeleton
`doc-network`	T5 Network Topology skeleton
`doc-postmortem`	T6 Postmortem skeleton
`doc-maintenance`	T7 Maintenance Window skeleton
`doc-release`	T8 Release Notes skeleton

8. FAQ

"Tôi chỉ cần viết 1 doc đơn giản, có cần dùng toolkit không?"

Có. Ngay cả doc đơn giản cũng nên có YAML header + markdown lint. Dùng CLI tạo trong 5 giây: docs-toolkit new howto "Task name" — nhanh hơn viết từ đầu.

"Skill file dài quá, đọc hết mất thời gian"

Không cần đọc hết. Chỉ cần đọc:

Iron Law (1 câu) — quy tắc quan trọng nhất
Guardrails (3-5 checkboxes) — verify trước khi viết
Remember (bảng cuối) — quick reference

"Tôi muốn viết loại doc mà không có template"

Dùng template gần nhất rồi customize. Hoặc tạo skill mới:

Copy skills/skill-template.md
Điền 6 sections bắt buộc
Submit PR (xem CONTRIBUTING.md)

"Docs-as-Code nghe phức tạp, team tôi chưa quen Git"

Bắt đầu từ Level 2 (xem Maturity Model trong Lifecycle Guide):

Docs trong Git repo (commit + push)
Dùng markdownlint (tự chạy qua pre-commit hook)
Sau đó mới thêm PR review, CI/CD, quarterly audit

"Toolkit này dùng cho AI agent được không?"

Có, đây là cách tiếp cận recommended. Toolkit có sẵn:

13 prompt templates trong prompts/ — copy-paste vào AI agent
AGENT-CARDS.json — agent scan nhanh tất cả skills
AGENTS.md — agent context file tự động load
Skills có cấu trúc chuẩn → AI đọc hiểu ngay (Iron Law, Guardrails, Decision Tree)

9. Tóm tắt

Cần viết doc?

  AI Agent (Recommended):
  → Chọn prompt từ prompts/
  → Copy + paste vào AI agent
  → Review + make lint → Commit

  Manual:
  → Chọn template (T1-T11)
  → Tạo bằng CLI: docs-toolkit new <type> "<title>"
  → Đọc Iron Law + Guardrails của skill tương ứng
  → Viết nội dung, điền placeholders
  → Lint: markdownlint + cspell
  → Preview: make serve
  → Commit + PR
  → Done!

3 files cần nhớ:

File	Mục đích
`skills/`	Đọc khi cần biết cách viết đúng
`templates/`	Đọc khi cần file mẫu copy-paste
`scripts/docs-toolkit`	Dùng khi cần tạo doc mới nhanh

FilesExpand file tree

getting-started.md

Latest commit

History