Cách viết README để người mới chạy được dự án trong 10 phút
Cách viết README để người mới chạy được dự án: cần có gì, gõ lệnh nào, thấy gì là đúng, lỗi thì làm sao, kèm script làm theo README trong thư mục trống.
Một README tốt trả lời bốn câu: cần có gì trên máy, gõ lệnh nào, thấy gì thì biết là đúng, và gặp lỗi thì làm sao. Hãy kiểm bằng cách làm theo nó trong thư mục trống, như một người mới. Bạn đã bao giờ clone dự án về rồi ngồi đoán cách chạy chưa?
Vì sao máy anh Khoa chạy được còn người mới thì không?
Ở tập trước của Nhận dự án cũ: từ bug report đến pull request, mình gom cấu hình của máy chủ đơn hàng vào một file config.ts và thêm .env.example. Anh Khoa (nhân vật minh họa trong series này) chạy được sau hai lần thử. Nhưng đó là vì anh ấy đã biết dự án. Một người mới vào nhóm thì không biết cần Node bản nào, có file nào phải sao chép, biến nào bắt buộc, và làm sao biết mình đã chạy đúng.
Dự án hiện có một file README, và nó trông như thế này. Đây là README-cu.md, bản mà phần lớn chúng ta viết ở lần đầu, gồm tên dự án và hai lệnh:
# Đơn hàng Mộc
Máy chủ đơn hàng của quán Mộc.
## Cài đặt
npm install
npm start(Trong file thật hai lệnh nằm trong một khối code bash; mình thụt vào ở đây để hiển thị gọn.) Nhìn thì không có gì sai. Hai lệnh đó là hai lệnh thật. Nhưng một người mới sẽ làm gì? Cách duy nhất để biết là thử.
Làm theo README như một người mới
Việc đầu tiên mình làm là viết một script đóng vai người mới. Script thu-readme.ts chép dự án sang một thư mục tạm, như vừa git clone: không có node_modules, không có .env (hai thứ này không nằm trong git). Sau đó nó lấy các lệnh npm ... trong khối bash của README, chạy từng lệnh theo thứ tự, và dừng ở bước đầu tiên hỏng. Riêng npm start chạy máy chủ không bao giờ tự thoát, nên script đợi dòng "nghe ở cổng", gửi một yêu cầu GET /don-hang, rồi tắt máy chủ.
import { spawn, spawnSync } from "node:child_process";
import { cpSync, mkdtempSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
const DU_AN = process.cwd();
const README = process.argv[2];
/** Các lệnh `npm ...` trong khối ```bash, theo thứ tự xuất hiện. */
export function layLenh(markdown: string): string[] {
const lenh: string[] = [];
for (const khoi of markdown.matchAll(/```bash\r?\n([\s\S]*?)```/g)) {
for (const dong of khoi[1]!.split(/\r?\n/)) {
const l = dong.replace(/\s+#.*$/, "").trim(); // bỏ chú thích cuối dòng
if (l.startsWith("npm ")) lenh.push(l);
}
}
return lenh;
}
const duoi = (chu: string, soDong = 6) => chu.trim().split(/\r?\n/).slice(-soDong).map((d) => " " + d).join("\n");
async function chayMayChu(thuMuc: string): Promise<string> {
const con = spawn("npm", ["start"], { cwd: thuMuc, shell: true });
let log = "";
con.stdout.on("data", (d) => (log += d));
con.stderr.on("data", (d) => (log += d));
const batDau = Date.now();
while (!/nghe ở cổng/.test(log) && con.exitCode === null && Date.now() - batDau < 8000) await new Promise((r) => setTimeout(r, 100));
let ketQua = "";
if (/nghe ở cổng/.test(log)) {
const phanHoi = await fetch("http://localhost:3000/don-hang");
const don = (await phanHoi.json()) as unknown[];
ketQua = `GET /don-hang → ${phanHoi.status}, ${don.length} đơn hàng`;
} else {
ketQua = "LỖI\n" + duoi(log);
}
spawnSync("taskkill", ["/PID", String(con.pid), "/T", "/F"], { shell: false }); // Windows; trên Linux/macOS dùng con.kill()
con.kill();
return ketQua;
}
if (process.argv[1]?.endsWith("thu-readme.ts")) {
if (!README) throw new Error("Cần tên file README, ví dụ: node thu-readme.ts README.md");
const thuMuc = mkdtempSync(join(tmpdir(), "readme-"));
cpSync(DU_AN, thuMuc, { recursive: true, filter: (nguon) => !/(^|[\\/])(node_modules|\.env)$/.test(nguon) });
const lenh = layLenh(readFileSync(join(DU_AN, README), "utf8"));
console.log(`${README}: ${lenh.length} lệnh npm trong khối bash, chạy trong thư mục trống`);
const batDau = Date.now();
let hong = false;
for (const l of lenh) {
process.stdout.write(`$ ${l} `);
if (l === "npm start") {
const ketQua = await chayMayChu(thuMuc);
console.log(ketQua);
hong = ketQua.startsWith("LỖI");
} else {
const kq = spawnSync(l, { cwd: thuMuc, shell: true, encoding: "utf8" });
hong = kq.status !== 0;
console.log(hong ? `LỖI (mã thoát ${kq.status})\n${duoi(kq.stdout + kq.stderr)}` : "ok");
}
if (hong) break;
}
console.log(`\n${hong ? "Người mới bị kẹt" : "Người mới chạy được"} sau ${((Date.now() - batDau) / 1000).toFixed(1)} giây (chưa tính thời gian đọc).`);
process.exitCode = hong ? 1 : 0;
}Mình chạy script này trong thư mục dự án (node thu-readme.ts README-cu.md) với README cũ:
README-cu.md: 2 lệnh npm trong khối bash, chạy trong thư mục trống
$ npm install ok
$ npm start LỖI
> start
> node --env-file=.env src/server.ts
node: .env: not found
Người mới bị kẹt sau 2.4 giây (chưa tính thời gian đọc).Người mới bị kẹt ở lệnh thứ hai, đúng chỗ mà README không nhắc gì: file .env. Và thông báo .env: not found không nói họ cần làm gì tiếp. Anh Khoa biết vì anh ấy đã làm trước; người mới thì không, và họ sẽ phải đi hỏi, hoặc đọc package.json, hoặc đoán.
Viết README thế nào để không ai bị kẹt?
Mình viết lại README theo bốn câu hỏi ở đầu bài, và thêm một thứ không nằm trong README mà nằm trong dự án: lệnh npm run setup. Lý do là nguyên tắc: nếu một bước trong README là "mở file này, sao chép, điền giá trị", thì thay vì bắt người mới làm tay, hãy viết một lệnh làm giúp. Tài liệu càng ít bước tay thì càng ít chỗ sai.
Script scripts/setup.ts tạo .env từ .env.example và điền sẵn một ORDER_API_KEY ngẫu nhiên. Chạy hai lần cũng an toàn, vì nếu .env đã có thì nó giữ nguyên, không bao giờ ghi đè khóa của bạn:
import { randomBytes } from "node:crypto";
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
export function taoEnv(thuMuc: string): "da-tao" | "da-co" {
const dich = join(thuMuc, ".env");
if (existsSync(dich)) return "da-co";
const mau = readFileSync(join(thuMuc, ".env.example"), "utf8");
const khoa = randomBytes(24).toString("hex");
writeFileSync(dich, mau.replace(/^ORDER_API_KEY=.*$/m, () => `ORDER_API_KEY=${khoa}`));
return "da-tao";
}
if (process.argv[1]?.endsWith("setup.ts")) {
const ketQua = taoEnv(process.cwd());
console.log(ketQua === "da-tao" ? "Đã tạo .env với một ORDER_API_KEY ngẫu nhiên." : ".env đã có, giữ nguyên.");
}Trong package.json, mình thêm "setup": "node scripts/setup.ts" vào mục scripts, và "engines": { "node": ">=22.18.0" } để phiên bản Node cũng được ghi lại ở một chỗ máy đọc được. Giờ đến README. Mình đi qua từng phần và nói vì sao nó có mặt.
Phần mở đầu chỉ cần hai câu: dự án này làm gì và ai dùng nó. Của mình là "Máy chủ nhận và trả danh sách đơn hàng của quán cà phê Mộc. Website của quán gửi đơn mới tới đây; nhân viên xem danh sách qua GET /don-hang." Người mới đọc xong biết ngay mình đang cầm cái gì, và biết có nên đọc tiếp không.
Mục "Cần có" liệt kê những thứ phải có trước khi gõ lệnh đầu tiên: Node.js 22.18 trở lên (kiểm tra bằng node --version), và npm. Mình ghi thêm một câu giải thích vì sao yêu cầu bản Node này: dự án chạy thẳng file .ts và dùng --env-file, nên Node cũ hơn sẽ lỗi. Một con số phiên bản không kèm lý do thì sau này không ai dám nâng hay hạ.
Mục "Chạy lần đầu" là mục quan trọng nhất, và nó gồm ba lệnh trong một khối bash, mỗi lệnh kèm một chú thích ngắn:
npm install
npm run setup # tạo .env từ .env.example, điền sẵn một ORDER_API_KEY ngẫu nhiên
npm start # máy chủ lắng nghe ở http://localhost:3000Ngay sau khối lệnh là câu mà mình thấy hay bị thiếu nhất ở README của người khác: "Mở http://localhost:3000/don-hang trong trình duyệt. Bạn sẽ thấy danh sách hai đơn hàng mẫu (JSON). Thấy vậy là xong." Người mới cần biết thế nào là thành công, nếu không họ không phân biệt được "đang chạy" với "chạy sai mà không báo".
Mục "Chạy test" chỉ có npm test và một dòng "Kết quả đúng: 23 test, tất cả pass". Mục "Cấu hình" trỏ tới .env.example thay vì chép lại danh sách biến, vì hai nơi cùng liệt kê một thứ sớm muộn sẽ lệch nhau. Mục "Cấu trúc thư mục" có bốn dòng, mỗi dòng một file và vai trò của nó. Cuối cùng là "Gặp lỗi?", và mình viết nó từ các lỗi có thật chứ không đoán. Mình chạy thử từng tình huống:
node: .env: not found
Cấu hình sai, máy chủ không khởi động:
- ORDER_API_KEY: phải dài ít nhất 16 ký tự
Error: listen EADDRINUSE: address already in use :::4555Mỗi lỗi có một dòng trong README: lỗi đầu là chưa chạy npm run setup, lỗi thứ hai là đọc từng dòng danh sách rồi sửa trong .env, lỗi thứ ba là cổng đang bận nên đổi PORT. (Lỗi thứ ba, mình thử ở cổng 4555 cho khỏi trùng máy; thông báo thật có cả một đoạn stack trace dài ở sau, một chỗ code máy chủ còn có thể thân thiện hơn.)
Giờ chạy lại script người mới, lần này với README mới:
README.md: 4 lệnh npm trong khối bash, chạy trong thư mục trống
$ npm install ok
$ npm run setup ok
$ npm start GET /don-hang → 200, 2 đơn hàng
$ npm test ok
Người mới chạy được sau 3.5 giây (chưa tính thời gian đọc).Cả bốn lệnh chạy được, máy chủ trả hai đơn hàng và test qua. 3,5 giây là thời gian của máy, không phải của con người: nó không tính việc đọc README, và nó chạy trên một máy đã có Node cùng mạng nhanh. Con số "10 phút" trong tiêu đề là mục tiêu mình đặt cho một người đọc thật, chứ mình chưa đo trên người nào.
README rồi cũng cũ đi
Chạy được hôm nay không có nghĩa chạy được tháng sau. Có người đổi tên src/config.ts, có người xóa script dev, và README vẫn nói điều cũ. Mình viết thêm kiem-readme.ts để bắt các lỗi hết hạn kiểu đó. Nó kiểm ba thứ: README có đủ năm mục không, mọi đường dẫn trong dấu huyền (` `) còn tồn tại không, và mọi lệnh npm run ... (cùng npm start, npm test) còn có script tương ứng trong package.json` không.
Lần chạy đầu của nó trên README mới của mình báo hai vấn đề, và cả hai đều sai:
README.md: 2 vấn đề
✗ Đường dẫn ".ts" không còn tồn tại.
✗ Đường dẫn "process.env" không còn tồn tại.Lỗi nằm ở bộ kiểm, không phải README. Bộ kiểm coi .ts và process.env là tên file vì chúng kết thúc bằng đuôi quen thuộc. Mình sửa luật nhận dạng đường dẫn: tên file phải có ít nhất một ký tự trước dấu chấm, và bỏ .env khỏi danh sách đuôi. Chạy lại, rồi thử trên hai README cố ý làm xấu. README-cu.md thiếu cả năm mục. README-het-han.md nhắc một file đã đổi tên và một script không còn:
README.md: không thấy vấn đề
README-cu.md: 5 vấn đề
✗ Thiếu mục "Cần có".
✗ Thiếu mục "Chạy lần đầu".
✗ Thiếu mục "Chạy test".
✗ Thiếu mục "Cấu hình".
✗ Thiếu mục "Gặp lỗi".
README-het-han.md: 2 vấn đề
✗ Đường dẫn "src/cau-hinh.ts" không còn tồn tại.
✗ Lệnh "npm run dev" nhưng package.json không có script "dev".Bộ kiểm này có giới hạn mà mình muốn kể bằng một chuyện thật. Khi viết bài này mình thêm test cho kiem-readme.ts, nên số test của dự án tăng từ 15 lên 23, và dòng "Kết quả đúng: 15 test" trong README lập tức sai. Bộ kiểm không bắt được, vì nó chỉ nhìn đường dẫn và tên script, không nhìn con số. Mình sửa tay thành 23. Nếu bạn không muốn gặp lại chuyện này, đừng ghi con số cụ thể, chỉ ghi "tất cả pass".
Mình không đưa các test ra đây (file kiem-readme.test.ts và scripts/setup.test.ts nằm trong repo demo). Chúng kiểm các điều đã nói: setup tạo khóa 48 ký tự hex, chạy lần hai không đổi khóa, hai máy nhận hai khóa khác nhau, process.env và .ts không bị coi là đường dẫn, và đường dẫn trong khối code hoặc URL không bị kiểm. Bạn chạy bằng npm test:
# tests 23
# pass 23
# fail 0Những điều README tốt không làm thay được
Mình nói thẳng các giới hạn. Script thu-readme.ts chỉ trả lời "máy có làm theo được README không", không trả lời "người có hiểu README không". README mà mọi lệnh đều chạy vẫn có thể khó đọc, thiếu bối cảnh, hoặc nói một thứ bằng từ chỉ nhóm mình biết. Cách thử đáng tin nhất vẫn là nhờ một người chưa biết dự án làm theo, và ngồi nhìn họ mà không gợi ý. Script cũng được viết và chạy trên Windows (nó dùng taskkill để tắt máy chủ), và mình chưa thử trên Linux hay macOS. Và README của mình chỉ nói về việc chạy dự án. Tài liệu của GitHub về README còn nhắc những thứ như dự án hữu ích vì sao, nhờ ai khi cần giúp đỡ, và ai duy trì nó. Với dự án mà người ngoài nhóm cũng đọc thì bạn nên thêm các phần đó.
Người mới chạy được rồi, vậy khi mình rời dự án thì sao?
Chuỗi bài này đã đi từ bug report tới pull request, và giờ dự án có README cho người đến sau. Nhưng chính mình, người đã sửa nhiều thứ trong hai tuần này, rồi cũng sẽ sang việc khác. Những gì mình biết về dự án, từ lý do sửa các lỗi đó tới các chỗ còn nợ, đang nằm trong đầu mình và rải rác ở các pull request. Gói chúng lại thành một bản bàn giao để người nhận không phải đào lại là việc của các bài viết sau.
Bạn theo dõi cả hành trình ở Nhận dự án cũ. Bài Zod validation giải thích cách kiểm tra dữ liệu mà config.ts đang dùng, và các câu hỏi về cách làm việc với dự án sẵn có nằm trong ngân hàng câu hỏi phỏng vấn.