Bộ skill chuẩn hóa cho documentation — dùng được cho mọi dự án, không phụ thuộc vào bất kỳ hệ thống cụ thể nào.
| Vấn đề | Toolkit giải quyết |
|---|---|
| Docs rải rác, format không thống nhất | 5 Skills chuẩn hóa cách viết mọi loại doc |
| Viết doc từ đầu mất thời gian | 11 Templates copy-paste, điền nội dung là xong |
| Không biết viết runbook/guide đúng cách | Mỗi skill có Iron Law + Guardrails |
| Docs cũ, không ai review | CI/CD pipeline: lint → review → deploy → audit |
| Mỗi người viết 1 kiểu | CLI tool tự tạo doc đúng format chuẩn |
Bước 1: CHỌN SKILL — Bạn cần viết gì?
| Skill | Khi nào dùng |
|---|---|
docs-engineer |
Setup MkDocs, chuẩn Markdown |
ops-runbook-writer |
Runbook, network, server docs |
training-doc-writer |
Training, onboarding, curriculum |
project-doc-writer |
ADR, tech spec, how-to, guide |
infra-security-doc |
Security policy, RBAC, audit |
Bước 2: TẠO DOCUMENT — Có 2 cách:
| Cách | Workflow |
|---|---|
| AI Agent (Recommended) | Copy prompt từ prompts/ → paste vào AI agent → review |
| Manual | ./scripts/docs-toolkit new runbook "Tên" → đọc skill → điền nội dung |
Bước 3: VERIFY & PUBLISH
markdownlint ✅ → PR review ✅ → mkdocs gh-deploy ✅
Lần đầu dùng? Đọc Getting Started Guide — hướng dẫn chi tiết từ A-Z.
Dùng AI agent? Xem Prompt Templates — 13 prompt templates sẵn sàng.
# Clone repo
git clone https://github.com/lampd-2157/documentation-skills-toolkit.git
cd documentation-skills-toolkit
# One-command setup (MkDocs + markdownlint + pre-commit)
bash scripts/setup.sh
# Tạo doc mới từ template
./scripts/docs-toolkit new runbook "My Service"
# Xem demo site
pip install -r demo-site/requirements.txt && make serve
# Hoặc dùng Makefile
make setup # One-command setup
make serve # Start dev server
make all # lint + validate + buildMỗi skill là một bộ quy tắc hướng dẫn cách viết 1 loại documentation cụ thể. Tất cả skills tuân thủ cùng cấu trúc 6 sections: Context → Iron Law → Guardrails → Red Flags → Remember → Related Skills.
| Skill | Khi nào dùng | Iron Law (quy tắc tối thượng) |
|---|---|---|
| docs-engineer | Setup MkDocs, chuẩn hóa markdown, chọn plugins | "Every document MUST pass markdownlint AND render correctly in MkDocs" |
| ops-runbook-writer | Viết runbook, ops manual, network/server docs | "Every runbook MUST have copy-paste commands AND expected output" |
| training-doc-writer | Viết training, onboarding, curriculum, learning path | "Every training doc MUST have Prerequisites → Steps → Expected Result → Troubleshooting" |
| project-doc-writer | Viết ADR, tech spec, how-to guide, quick reference | "Every project doc MUST have Context → Decision/Steps → Consequences/Result" |
| infra-security-doc | Viết security policy, RBAC, audit log, vulnerability | "Every security doc MUST have Scope → Policy → Enforcement → Audit" |
Copy-paste từ templates/, hoặc dùng CLI:
| ID | Template | CLI command | Use Case |
|---|---|---|---|
| T1 | Runbook | docs-toolkit new runbook "Name" |
Vận hành hệ thống |
| T2 | ADR (Nygard) | docs-toolkit new adr "Decision" |
Architecture decision |
| T3 | How-to Guide | docs-toolkit new howto "Task" |
Hướng dẫn step-by-step |
| T4 | Training Module | docs-toolkit new training "Topic" |
Training nội bộ |
| T5 | Network Topology | docs-toolkit new network "Env" |
Document network infrastructure |
| T6 | Incident Postmortem | docs-toolkit new postmortem "Title" |
Phân tích sau sự cố |
| T7 | Maintenance Window | docs-toolkit new maintenance "Title" |
Kế hoạch bảo trì |
| T8 | Release Notes | docs-toolkit new release-notes "vX.Y" |
Tóm tắt version release |
| T9 | ADR (MADR) | docs-toolkit new adr-madr "Decision" |
Complex decision, nhiều options |
| T10 | ADR (Lightweight) | Copy templates/adr-lightweight.md |
Quick decision, POC |
| T11 | Knowledge Check | docs-toolkit new knowledge-check "Topic" |
Kiểm tra kiến thức |
| Tool | Command | Mô tả |
|---|---|---|
| Scaffold | ./scripts/docs-toolkit new <type> <title> |
Tạo doc mới từ template |
| Validate | python3 scripts/validate_skill.py |
Kiểm tra cấu trúc skill file |
| Lint | npx markdownlint-cli2 "**/*.md" |
Kiểm tra markdown format |
| Spell | npx cspell "**/*.md" |
Kiểm tra chính tả |
| Preview | make serve |
Xem trước trên localhost:8000 |
| Score | python3 scripts/score_docs.py |
Chấm điểm chất lượng doc (6 criteria) |
| Build | mkdocs build --strict |
Build production |
documentation-skills-toolkit/
├── skills/ # 5 skills + template + AGENT-CARDS.json
├── templates/ # 11 document templates (T1-T11), individual files
├── prompts/ # 13 prompt templates cho AI agent
├── docs/ # Guides: getting-started, lifecycle, recipes...
├── config/ # Configs: markdownlint, cspell, pre-commit...
├── examples/ # Starter configs cho project khác (mkdocs, CI, snippets)
├── scripts/ # CLI tools: setup.sh, docs-toolkit, validate_skill.py
├── evals/ # Eval test suite cho mỗi skill
├── demo-site/ # MkDocs demo site
├── .github/workflows/ # CI/CD: lint + validate + build
├── Makefile # make serve/lint/validate/build
├── README.md / CHANGELOG.md / CONTRIBUTING.md / LICENSE
| Doc | Mô tả | Đọc khi... |
|---|---|---|
| Getting Started | Hướng dẫn từ A-Z cho người mới | Lần đầu dùng toolkit |
| Walkthrough | Step-by-step tạo document đầu tiên | Muốn làm theo ví dụ cụ thể |
| Lifecycle Guide | Write → Lint → Review → Publish → Audit | Setup Docs-as-Code pipeline |
| Composition Recipes | Kết hợp skills cho task thực tế | Không biết dùng skill nào |
| Quality Scorecard | Chấm điểm chất lượng doc (0-10) | Review / audit docs |
| Anti-Patterns | 10 lỗi documentation phổ biến | Tránh sai lầm khi viết |
| Plugin Catalog | MkDocs plugins chọn lọc | Mở rộng MkDocs site |
| Infra Knowledge Base | Cấu trúc docs cho team infra | Team infra/ops mới bắt đầu |
| ADR Catalog | Chọn ADR format + lifecycle + naming | Viết architecture decision |
| Incident Patterns | Failure taxonomy + prevention controls | Phân tích incident/postmortem |
| Training Assessment | Bloom's Taxonomy + assessment design | Thiết kế bài kiểm tra |
| Diátaxis Mapping | Map toolkit → Diátaxis framework | Organize docs theo chuẩn quốc tế |
| Prompt Templates | Prompt chuẩn cho AI agent tạo docs | Dùng AI tạo docs |
| Security Placeholders | Quy chuẩn placeholder cho sensitive data | Docs chứa IPs, passwords, tokens |
| Case Study: Ansible | Ví dụ thực tế v5.0.0 workflow end-to-end (Smart Routing + Interview) | Xem toolkit hoạt động thế nào |
| AGENTS.md | Agent context file (tool-agnostic) | AI agent đọc trước khi làm việc |
| Routing Playground | Test Smart Routing với natural language input | Hiểu cách routing hoạt động |
| Contributing | Cách đóng góp skills & templates | Muốn thêm skill/template mới |
| Community Skills | Marketplace cho community-contributed skills | Muốn đóng góp skill mới |
MIT — LICENSE
Created by DulapReal — Infrastructure & Automation Engineer
Version 5.4.0 | 2026-03-30