📱 Học IELTS miễn phí: App IELTS 6.0

Giới Thiệu

Bạn join dự án mới, mở repository và thấy:

  • README.md: “TODO: add docs”
  • Wiki: trống trơn
  • Architecture diagram: không tồn tại

😱 Kết quả? Mất 2 tuần onboarding thay vì 2 ngày.

Technical documentation (tài liệu kỹ thuật) là kỹ năng mà hầu hết developer đều biết là quan trọng… nhưng ít ai viết tốt, đặc biệt bằng tiếng Anh.

Bài viết này sẽ giúp bạn:

  • Hiểu các loại technical documentation
  • Nắm cấu trúc chuẩn cho từng loại
  • Có template copy-paste ngay được
  • Học từ vựng và mẫu câu chuyên dụng

1. Các Loại Technical Documentation

Bảng Tổng Quan

Loại tài liệuMục đíchĐối tượng
READMEGiới thiệu dự án, hướng dẫn cài đặtMọi người
API DocumentationMô tả endpoints, request/responseFrontend dev, đối tác
Architecture DocumentThiết kế hệ thống tổng quanDev team, architect
RunbookHướng dẫn vận hành, xử lý sự cốDevOps, SRE
ADR (Architecture Decision Record)Ghi lại quyết định kiến trúcDev team hiện tại & tương lai
ChangelogLịch sử thay đổiUsers, dev team
Onboarding GuideHướng dẫn cho người mớiNew team members

2. README — Bộ Mặt Của Dự Án

README là thứ đầu tiên mọi người đọc. Một README tốt = onboarding nhanh hơn 10 lần.

Cấu Trúc Chuẩn

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Project Name

Brief description of what this project does and why it exists.

## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

## Features
- Feature 1: Brief description
- Feature 2: Brief description

## Prerequisites
- Node.js >= 18.0
- PostgreSQL >= 14
- Docker (optional)

## Installation

```bash
git clone https://github.com/org/project.git
cd project
npm install
cp .env.example .env

Usage

1
2
3

npm run dev        # Start development server
npm run build      # Build for production
npm run test       # Run tests

Configuration

VariableDescriptionDefault
PORTServer port3000
DB_URLDatabase connection string-

Contributing

Please read CONTRIBUTING.md for details.

License

This project is licensed under the MIT License.

###`##B#H####D##---#L###`#r#o####e###i#ETBMCSC#`Aiw##sRRATAJRnnhualeo3mr1e23******4c5eevh6lWa7kMgiikoen.Cac.f.t.3RTC3RTD.r.qsar.lTt.ẫlslentấrhh.eeo.eeaiupio-etuitetrAukiOdCeC1scm2sctDbNioluStbTospshirdtveoophmphaaeornageralrChrwutebcToeesnsmAonuUonbtnesbhcasiarâoirhuhrwcrctypPnonsnoaah-meipufemdeu|jtee[tiúntvresoIslieslsoFelurfdielehditcuiixtniocrioeFwuntitiit-eHTcyrooerepteeGbgabg:lntittcaiovait[oecncCewtmnaiytSiy*odcmy|yunfayếtupssthiDttl:iel:*wateetgfnnpeo]uuDoifsei*ori*ti|1Cnh:stDgrchsarẩonaiwt*nvt*PaoT|0oceùohaifrencgtay:iyona90nrn1aAnVvnvtoeuorsy:K*c:Nsmar<90syt0nDgiioeorDmfa*o*e*otolg.ipi0dRệdl.rwoemi*n*dgve29RdtcsTteo.ymecntngRereRt0%PeearD.rsg.oluthtREM.ese0Srdteeo|.yarcmeoo/SajSqm|aiqcn.]ineoe—uTnsQtus|tvo/ig.ndmnsttAaLhiiinmssdet[yheWg+rr(oaiiR|tre!SseSveoepnnoEĐaut—ytaeEum9sTnADưlna|selnAruxge5LpsDựợl.iTtmadPsphn)SeMce.lCherIHertrEád.shimagaTrets1nxàếneuGTsh.uâtNdrtaPase3snyahtSceàĐCXđKmieeecsrydảleóếetcnwoyựmomn]sotauscnnHsiyntugbe[mệpyctenảtọusasmgboràiTrtt.ằeihpeeacnbpđốomnấgạolóns.rdpningee.[vệg.qa.cđàuuu.ôã]getncóshgchđpteàạể!snniytg..b|ih..icệ..ếa]tti|tohnêmchitiết|

Từ Vựng Architecture Document

EnglishIPATiếng Việt
scalability/ˌskeɪ.ləˈbɪl.ə.ti/khả năng mở rộng
availability/əˌveɪ.ləˈbɪl.ə.ti/tính sẵn sàng
throughput/ˈθruː.pʊt/thông lượng
latency/ˈleɪ.tən.si/độ trễ
trade-off/ˈtreɪd.ɒf/sự đánh đổi
bottleneck/ˈbɒt.əl.nek/nút thắt cổ chai
fault tolerance/fɔːlt ˈtɒl.ər.əns/chịu lỗi
idempotent/ˌaɪ.dɛmˈpoʊ.tənt/lũy đẳng
eventual consistency/ɪˌven.tʃu.əl kənˈsɪs.tən.si/nhất quán cuối cùng
single point of failure/ˌsɪŋ.ɡəl pɔɪnt əv ˈfeɪ.ljər/điểm lỗi đơn

4. Runbook — Sổ Tay Vận Hành

Runbook giúp team xử lý sự cố nhanh chóng mà không cần “người biết” online.

Cấu Trúc Chuẩn

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Runbook — [Service Name]

## Alert: High CPU Usage

### Severity: P2 (High)

### Symptoms
- CPU usage > 90% for more than 5 minutes
- Response time degraded (> 2s p95)
- Alert fired: `cpu_usage_critical`

### Diagnosis Steps
1. Check current CPU usage:
   ```bash
   kubectl top pods -n production
  1. Identify the problematic pod:
    1

    kubectl logs <pod-name> --tail=100
  2. Check for recent deployments:
    1

    kubectl rollout history deployment/api-server

Resolution

Option A — Scale horizontally:

1

kubectl scale deployment/api-server --replicas=5

Option B — Rollback if caused by recent deploy:

1

kubectl rollout undo deployment/api-server

Escalation

If unresolved after 15 minutes, escalate to:

  • On-call SRE: #sre-oncall Slack channel
  • Engineering Manager: @jane.doe
##A#`####WTa#W###---#--#-##D#`###ehn#e######ETFIETNR#`AedOMMP#FJR#TH#Vnhifsho5mDSDCnDwApyooCuSieoeMgirci.gTaRtaoesJeiltSnsoPlOcNarRnẫlsstasaher-atneyScltiQgtnolNhemiiduithlcAimk0tetdsOileoLogssBgzsosa,eaitDpd0u:etNsrnDreiAeanokrChltsiRllo1sxaeiun|BeqtCsxtensâevieoạaw::2tmsosaSuiIutietlu|resan—itn0rtnetF|QevDpevdaotrsteUA2eroiPaLnepneslcHTiuokrAsc6lerPvrmFccoskaiffener*Aec-aqaoeoil|eorits-yếiy[oqctDe0tugssslesmtorcinrptwuhạRPp4iietixSpnaanDgeteeniiiot-orgCaitlfilùshrartse0nefrorbrioenitnVasmieestd9asoenCloarcinogiwti]sdcaglrSsotennongệh.ss;torAQinogcfsgPTte.tiuu*edCfLdsselyrorn.sfetr*SaIletcJesoeso|..heQtDe1rehSfxtnqtn..ucitLax6eaeOoieugg..nasDebtidmmNrbmPirĐrueaaarba,a,loreR|ầ|esicmssals,oe(seSuusesienegArPtsQnCNodsđPsooeCdpogLbảtếleiưrfapuoaIersrm-oniuvbxoaiocrrdsDroteosohêeypnmrtoy,dGSrpknvd.eraidpptuIQeeb,ấ.cRaroouresercSLcána.teyuncircxat,-pioxfecqrstmfatnslfáđt|douD,aolessppaincềeryaearrinacgencàrĐbdết-ctymnsch_cnynvâetacotagiteviifhẫ[yhbomrdnoimefnekậntađampiac|noacigaínilvịsmlbtesnstctctmàineeeuaNso(uhrieohrxtbrfCrằế]vrcea)eiehnpấkeqssWASatsog|n|ỹu.eeCltuạ.tpe.aIius(t.ụCđKtlrkDgr,J.chềhhaieheSk.uôuteratsrOh.yđnậfscleNi.ểãgto,JryaB.nrSod.bc—mOsho.liầ.Nsarpêếnvreentôscdprxuoela[dửcplrittoùplcoe.lnoeoara.ýgrcpssm.;tts))]qiđunâanếynsult|càrhọưhnaàgnghcihảvoiinqbguìưynờếhittjshoaưiuờnn[gstah|uờ.igian]|

6. Best Practices — Viết Documentation Tốt

✅ Nên Làm

PracticeVí dụ
Use active voice“The system sends a notification” ✅ (không phải “A notification is sent”)
Be specific“Responds within 200ms” ✅ (không phải “Responds quickly”)
Include examplesLuôn có code snippet hoặc sample request
Keep it updatedThêm vào Definition of Done: “Update docs”
Use consistent terminologyChọn 1 từ và dùng xuyên suốt (user vs. customer — chọn 1)
Add diagrams“A picture is worth a thousand words” — dùng Mermaid, PlantUML

❌ Không Nên

Lỗi thường gặpVấn đề
“This is self-explanatory”Không bao giờ self-explanatory cho người mới
Quá dài, quá chi tiếtKhông ai đọc. Viết ngắn gọn, link đến chi tiết
Copy-paste code cũCode thay đổi, docs không update = misleading
Viết 1 lần rồi quênDocs outdated = docs dangerous

7. Từ Vựng Technical Writing

EnglishIPATiếng Việt
prerequisite/priːˈrek.wɪ.zɪt/điều kiện tiên quyết
boilerplate/ˈbɔɪ.lə.pleɪt/mẫu có sẵn, code/text lặp lại
deprecated/ˈdep.rə.keɪ.tɪd/không còn được khuyên dùng
out of scope/aʊt əv skoʊp/ngoài phạm vi
edge case/edʒ keɪs/trường hợp biên
caveat/ˈkæv.i.æt/lưu ý, cảnh báo
verbose/vɜːrˈboʊs/chi tiết, dài dòng
concise/kənˈsaɪs/ngắn gọn, súc tích
stakeholder/ˈsteɪk.hoʊl.dər/bên liên quan
maintainability/meɪnˌteɪ.nəˈbɪl.ə.ti/khả năng bảo trì

8. Mẫu Câu Thường Dùng Khi Viết Docs

Giới thiệu

  • “This document describes the architecture of…”
  • “The purpose of this guide is to help developers…”
  • “This section covers the setup and configuration of…”

Hướng dẫn

  • “To get started, you need to…”
  • “Make sure the following dependencies are installed:…”
  • “Run the following command to…”
  • “See [section] for more details.”

Cảnh báo

  • "⚠️ Note: This operation is irreversible."
  • "⚠️ Important: Do not run this in production without…"
  • “This feature is deprecated and will be removed in v3.0.”

Tham khảo

  • “For further reading, see…”
  • “Refer to the [API docs] for the full list of endpoints.”
  • “This decision is documented in ADR-001.”

9. Practice — Bài Tập Thực Hành

Bài tập 1: Viết README

Chọn một side project của bạn và viết README theo cấu trúc ở mục 2. Đảm bảo có đủ:

  • Project description
  • Prerequisites
  • Installation steps
  • Usage examples
  • Configuration table

Bài tập 2: Viết ADR

Nghĩ về một quyết định kỹ thuật gần đây (chọn framework, database, hosting…) và viết ADR theo template ở mục 5. Bao gồm:

  • Context (tại sao cần quyết định)
  • Alternatives considered (so sánh ít nhất 2 lựa chọn)
  • Consequences (positive + negative)

Bài tập 3: Sửa lỗi

Các câu sau có vấn đề gì? Viết lại cho tốt hơn:

  1. “The data is processed by the system.” → Chuyển sang active voice
  2. “This is fast.” → Thêm con số cụ thể
  3. “Just run the script.” → Thêm hướng dẫn chi tiết
📝 Đáp án gợi ý
  1. “The system processes the data.” hoặc “The system processes incoming data within 50ms.”
  2. “The API responds within 200ms at the 95th percentile.”
  3. “Run the migration script: npm run db:migrate. This applies all pending database migrations.”

Kết Luận

“The palest ink is better than the best memory.” — Proverb

Documentation không glamorous, nhưng nó là thứ phân biệt team chuyên nghiệp và team nghiệp dư.

Bắt đầu nhỏ:

  1. Viết README cho project hiện tại
  2. Ghi ADR cho quyết định kỹ thuật tiếp theo
  3. Tạo runbook cho service quan trọng nhất

Mỗi ngày viết thêm một chút — 6 tháng sau, team bạn sẽ cảm ơn bạn (và bạn của 6 tháng trước cũng sẽ cảm ơn chính mình) 📝✨