Mở đầu — vì sao bài này quan trọng
Có một sự thật khó chịu mà ít ai nói thẳng với bạn khi mới vào nghề: code của bạn hầu như không ai đọc, nhưng doc của bạn thì có thể được hàng trăm người đọc.
Hãy nghĩ kỹ về điều này. Một hàm bạn viết cực kỳ tinh tế, tối ưu từng dòng, có thể chỉ được đúng người review PR đọc qua — hai, ba, cùng lắm là năm người. Sau đó nó nằm im trong repo, chạy âm thầm, và không ai ngó lại trừ khi có bug. Trong khi đó, một tài liệu bạn viết tốt — hướng dẫn setup môi trường, giải thích kiến trúc hệ thống, runbook xử lý sự cố — có thể được đọc bởi mọi thành viên mới, mọi kỹ sư ở team khác cần tích hợp, mọi người trực on-call lúc 2 giờ sáng. Doc của bạn được nhân bản ra hàng trăm lượt đọc, và mỗi lượt đọc đó là một lần tên bạn, tư duy của bạn, giá trị của bạn được nhìn thấy.
Đây chính là "hidden ROI" — lợi tức ẩn — của documentation. Với tư cách một Individual Contributor (IC, kỹ sư đóng góp trực tiếp), phần lớn công sức của bạn là vô hình. Bạn fix bug, bạn refactor, bạn giúp đồng nghiệp debug qua DM — tất cả đều quý giá nhưng không để lại dấu vết. Documentation là một trong số ít loại công việc kỹ thuật vừa tạo ra giá trị thật, vừa để lại dấu vết có tên bạn trên đó, vừa được tiêu thụ rộng rãi.
Trong bài này, chúng ta không học cách viết một tài liệu tốt (Bài 9, Bài 39 đã lo phần kỹ thuật viết doc và onboarding docs). Bài 46 tập trung vào một góc nhìn khác hẳn: coi documentation như một đòn bẩy sự nghiệp — công cụ tạo visibility, nhiên liệu cho promotion, và cách bạn biến việc viết doc từ "công việc phụ ai cũng né" thành lợi thế cạnh tranh của riêng mình.
Khái niệm cốt lõi
Documentation là "leverage" — đòn bẩy, không phải chi phí
Trong kinh tế học có khái niệm leverage: một đơn vị đầu vào tạo ra nhiều đơn vị đầu ra. Documentation là dạng leverage thuần túy nhất trong công việc kỹ thuật. Bạn viết một lần, nó phục vụ vô số lần. Bạn bỏ ra 3 giờ viết doc "Cách deploy service X", và tiết kiệm cho 20 đồng nghiệp mỗi người 30 phút hỏi han, mò mẫm — đó là 10 giờ tiết kiệm cho team từ 3 giờ của bạn. Tỷ lệ đòn bẩy hơn 3 lần, và còn tăng dần theo thời gian khi có thêm người đọc.
Nhiều kỹ sư trẻ Việt Nam coi viết doc là "việc chân tay", là thứ để làm cho có lệ khi manager nhắc. Đó là sai lầm về mặt chiến lược sự nghiệp. Người hiểu leverage sẽ nhìn thấy: viết doc là cách rẻ nhất để nhân bản tầm ảnh hưởng của bản thân mà không cần thêm chức danh, không cần quản lý ai.
Ba trục giá trị: Visibility, Promotion fuel, Trust
Documentation nâng đỡ sự nghiệp qua ba trục:
1. Visibility (khả năng được nhìn thấy). Đây là trục quan trọng nhất và bị đánh giá thấp nhất. Ở các công ty từ 50 người trở lên, sếp của sếp bạn không biết bạn làm gì hằng ngày. Họ không đọc code bạn. Nhưng họ đọc doc — nhất là design doc, RFC, postmortem được lan truyền trong công ty. Khi tên bạn đứng đầu một tài liệu mà nhiều người tham chiếu, bạn tồn tại trong nhận thức của những người ra quyết định về lương thưởng và thăng tiến.
2. Promotion fuel (nhiên liệu thăng tiến). Hầu hết framework thăng tiến (từ Junior lên Mid, Mid lên Senior, Senior lên Staff) đều có tiêu chí về "impact vượt ra ngoài phạm vi công việc cá nhân" và "nâng đỡ người khác". Một câu như "Tôi viết bộ tài liệu onboarding giúp thời gian ramp-up của kỹ sư mới giảm từ 3 tuần xuống 1 tuần" là bằng chứng promotion cực mạnh — nó cụ thể, đo được, và cho thấy tầm ảnh hưởng nhân rộng. Code không nói được điều đó; doc thì có.
3. Trust (niềm tin). Người viết doc rõ ràng được ngầm định là người suy nghĩ rõ ràng. Khi đồng nghiệp và sếp liên tục thấy bạn diễn giải vấn đề phức tạp thành văn bản mạch lạc, họ tin bạn nắm chắc chuyên môn. Niềm tin đó chuyển thành việc bạn được giao dự án lớn hơn, được mời vào các cuộc bàn kiến trúc — vòng lặp tích cực cho sự nghiệp.
Doc là tài sản, không phải sự kiện
Điểm mấu chốt về mặt tư duy: một buổi họp là sự kiện — nó diễn ra rồi biến mất, giá trị bằng không sau khi kết thúc. Một tài liệu là tài sản — nó tiếp tục sinh lợi tức lâu sau khi bạn viết xong. Khi bạn dành thời gian, hãy tự hỏi: "Tôi đang tạo ra sự kiện hay tài sản?" Người xây dựng sự nghiệp bền vững ưu tiên tạo tài sản.
"Meta-doc": doc về việc viết doc cũng là leverage
Một tầng cao hơn: nếu bạn không chỉ viết doc tốt mà còn thiết lập chuẩn viết doc cho team (template RFC, quy ước cho ADR, checklist cho postmortem), bạn tạo ra leverage bậc hai — bạn ảnh hưởng đến cách hàng chục người khác viết. Đây là dấu hiệu của tư duy Staff/Principal.
Tình huống thực tế
Tình huống 1 — Kỹ sư "vô hình" ở một fintech tại TP.HCM
Minh là backend engineer ở một công ty fintech khoảng 120 người tại Quận 1, TP.HCM. Anh giỏi thật sự: giải quyết những bug hóc búa nhất về xử lý giao dịch, thường được đồng nghiệp gọi tên khi có sự cố. Nhưng suốt hai kỳ đánh giá liên tiếp, Minh trượt promotion lên Senior. Lý do manager đưa ra: "Impact của em khó chứng minh với hội đồng thăng tiến. Họ không thấy được đóng góp của em."
Minh thất vọng, nhưng anh làm một thí nghiệm. Trong quý tiếp theo, mỗi lần xử lý xong một sự cố lớn, anh viết một tài liệu ngắn — không phải postmortem chính thức, mà là "cách hệ thống thanh toán của chúng ta thực sự hoạt động ở phần X, và những cạm bẫy đã gặp". Anh đưa vào Confluence của công ty, gắn link trong kênh Slack #engineering.
Sau 4 tháng, có 6 tài liệu như vậy. Điều bất ngờ: đội Data, đội Mobile, thậm chí một PM đều bắt đầu link tới tài liệu của Minh khi thảo luận. Khi kỳ đánh giá tới, manager của Minh chỉ cần mở dashboard: "6 tài liệu, tổng cộng hơn 400 lượt xem, được 3 team khác tham chiếu." Hội đồng promotion không cần phải "tin lời" nữa — bằng chứng nằm ngay đó, đo được. Minh lên Senior.
Bài học: Năng lực của Minh không đổi giữa hai kỳ đánh giá. Cái thay đổi là khả năng năng lực đó được nhìn thấy. Documentation biến công việc vô hình thành tài sản có thể trỏ tay vào.
Tình huống 2 — "Grab-style" onboarding doc cứu một team đang chảy máu thời gian
Một startup logistics tại Singapore (khoảng 60 kỹ sư, phục vụ thị trường Đông Nam Á) có vấn đề kinh điển: mỗi kỹ sư mới mất trung bình 3 tuần mới commit được dòng code có ý nghĩa đầu tiên, vì môi trường dev cực kỳ rối rắm — 8 microservice, cấu hình phức tạp, kiến thức nằm rải rác trong đầu các "cây đa cây đề".
Lan, một Mid-level engineer, quyết định làm việc mà ai cũng thấy cần nhưng không ai chịu làm: viết một bộ onboarding doc hoàn chỉnh, có mục lục, có phần "nếu gặp lỗi này thì làm gì", và một script tự động hóa setup. Cô bỏ ra khoảng 5 ngày làm việc rải rác trong 3 tuần.
Kết quả đo được sau 6 tháng: thời gian ramp-up trung bình giảm từ 3 tuần xuống còn 6 ngày. Với 10 kỹ sư mới trong nửa năm, đó là tiết kiệm khoảng 150 ngày công. Trong buổi review cuối năm, con số này được chính giám đốc kỹ thuật nhắc tới trước toàn bộ phòng. Lan không "code nhiều hơn ai" trong quý đó, nhưng cô được đề bạt vì tạo ra impact rõ rệt và nhân rộng.
Bài học: Doc có ROI đo lường được. Khi bạn gắn con số vào (giảm bao nhiêu thời gian, cho bao nhiêu người), bạn biến một "việc tốt bụng" thành một câu chuyện impact không thể chối cãi.
Tình huống 3 — Cái bẫy của doc không ai đọc
Không phải cứ viết doc là có leverage. Đức, một kỹ sư nhiệt tình ở một công ty game tại Hà Nội, viết rất nhiều — nhưng anh viết theo kiểu "nhật ký kỹ thuật": dài dòng, không có mục lục, không cho ai biết chúng tồn tại, chôn sâu trong một thư mục Google Drive cá nhân. Sau một năm, anh có 30 tài liệu và... gần như không lượt xem nào. Khi anh nhắc tới chúng trong buổi review, manager thẳng thắn: "Nếu không ai đọc thì nó không tạo ra giá trị cho ai cả."
Đức chỉnh lại chiến lược: viết ít hơn nhưng đúng thứ người khác đang cần (những câu hỏi lặp đi lặp lại trên Slack), đặt ở nơi mọi người tìm được, và chủ động thông báo khi có doc mới. Số lượng doc giảm một nửa, nhưng lượt đọc tăng gấp 10 lần.
Bài học: Leverage của doc = giá trị × số người tiếp cận. Một tài liệu xuất sắc mà không ai biết đến có leverage bằng không. Phần "phân phối" (distribution) quan trọng ngang phần "viết".
Hướng dẫn từng bước
Dưới đây là quy trình biến documentation thành đòn bẩy sự nghiệp một cách hệ thống:
Bước 1 — Săn "pain point lặp lại". Đừng viết doc ngẫu nhiên. Hãy để ý những câu hỏi được hỏi đi hỏi lại trên Slack/Discord, những chỗ mọi người luôn vấp khi setup, những sự cố cứ tái diễn. Mỗi câu hỏi lặp lại là một doc đang chờ được viết — và vì nó lặp lại, bạn biết chắc sẽ có người đọc.
Bước 2 — Viết cho "người đọc tương lai đang hoảng loạn". Hãy tưởng tượng người đọc là một kỹ sư mới, đang gặp lỗi, đang chịu áp lực. Viết ngắn gọn, có mục lục, có phần "triệu chứng → nguyên nhân → cách xử lý". Đặt kết luận và câu trả lời quan trọng lên đầu (nguyên tắc BLUF — Bottom Line Up Front).
Bước 3 — Đặt doc ở nơi người ta tìm được. Doc phải nằm trong hệ thống chung của công ty (Confluence, Notion, wiki của repo, README), không phải Drive cá nhân. Nơi đúng là nơi người ta sẽ tìm khi cần, không phải nơi tiện cho bạn.
Bước 4 — Chủ động phân phối. Sau khi viết xong, đăng link vào kênh phù hợp với một dòng tóm tắt: "Mình vừa viết doc về X, ai gặp Y có thể tham khảo." Ghim vào kênh nếu được. Distribution là phần bị bỏ quên nhiều nhất.
Bước 5 — Đo lường và ghi lại. Ghi chú lượt xem, số lần được tham chiếu, phản hồi tích cực. Nhiều công cụ wiki hiển thị view count. Lưu những con số này vào một file "brag doc" cá nhân (nhật ký thành tích) — bạn sẽ cần chúng khi review.
Bước 6 — Duy trì (giữ doc sống). Doc lỗi thời còn tệ hơn không có doc, vì nó gây hiểu nhầm. Đặt lịch rà soát định kỳ những doc quan trọng của bạn. Người duy trì được một tài sản tài liệu đáng tin sẽ được nhớ tới như "người sở hữu mảng đó".
Bước 7 — Nâng cấp lên meta. Khi đã thành thạo, hãy tạo template và chuẩn cho team. Đây là bước biến bạn từ "người viết doc tốt" thành "người định hình văn hóa doc" — tín hiệu cho cấp bậc cao hơn.
Lỗi thường gặp & mẹo
Lỗi 1 — Viết doc rồi giấu. Như tình huống của Đức. Không phân phối = không leverage. Mẹo: dành 5 phút cuối cùng để đăng link và thông báo — coi nó là phần bắt buộc của công việc, không phải tùy chọn.
Lỗi 2 — Cầu toàn đến mức không bao giờ publish. Nhiều người ôm doc "chưa hoàn hảo" hàng tuần. Một doc 80% publish hôm nay có giá trị hơn một doc 100% mãi mãi trong bản nháp. Mẹo: publish sớm, đánh dấu "draft" nếu cần, cải thiện dần theo phản hồi.
Lỗi 3 — Không gắn con số vào impact. "Tôi viết một số doc" là câu vô nghĩa trong buổi review. Mẹo: luôn đóng khung theo kết quả — giảm bao nhiêu thời gian, bao nhiêu lượt đọc, bao nhiêu team dùng.
Lỗi 4 — Chờ được giao mới viết. Doc leverage cao nhất thường là doc không ai giao cho bạn — bạn tự nhận ra khoảng trống và lấp vào. Đó chính là dấu hiệu "ownership" mà framework promotion tìm kiếm.
Lỗi 5 — Coi viết doc là việc thấp kém. Đây là định kiến văn hóa cần bỏ. Ở nhiều công ty tech hàng đầu, kỹ năng viết là một trong những yếu tố phân biệt Senior với Staff. Đầu tư vào nó là đầu tư vào trần thu nhập của bạn.
Mẹo vàng — Duy trì "brag doc" song song. Mỗi khi viết doc có tác động, ghi một dòng vào file thành tích cá nhân: tên doc, ngày, kết quả đo được. Đến kỳ review, bạn có sẵn kho bằng chứng thay vì phải nhớ lại trong hoảng loạn.
Bài tập thực hành
Bài tập 1 — Audit pain point (30 phút). Lướt lại kênh Slack/Discord team bạn trong 2 tuần gần nhất. Liệt kê 5 câu hỏi được hỏi từ 2 lần trở lên. Đây chính là danh sách 5 doc có leverage cao nhất bạn có thể viết ngay.
Bài tập 2 — Viết một doc và phân phối (tuần này). Chọn 1 pain point từ bài tập 1. Viết một doc ngắn (dưới 1 trang) theo cấu trúc "triệu chứng → cách xử lý", đặt vào wiki chung, và đăng link kèm một dòng thông báo. Ghi lại ngày đăng.
Bài tập 3 — Đo lường sau 2 tuần. Quay lại doc đã đăng, ghi nhận: bao nhiêu lượt xem, có ai nhắc/tham chiếu không, có phản hồi gì. Viết một câu "impact statement" theo mẫu: "Tôi viết doc về ___, được ___ người đọc/dùng, giúp ___."
Bài tập 4 — Khởi tạo brag doc. Tạo một file cá nhân tên "brag-doc" hoặc "nhật ký thành tích". Thêm mục đầu tiên là doc bạn vừa viết ở bài tập 2. Đặt lịch nhắc bổ sung mỗi 2 tuần.
Tóm tắt
- Doc được đọc bởi nhiều người hơn code rất nhiều — đó là loại leverage thuần túy nhất trong công việc kỹ thuật: viết một lần, sinh lợi tức mãi mãi.
- Documentation nâng đỡ sự nghiệp qua ba trục: Visibility (được người ra quyết định nhìn thấy), Promotion fuel (bằng chứng impact đo được), và Trust (viết rõ = nghĩ rõ).
- Doc là tài sản, không phải sự kiện — nó tiếp tục sinh giá trị lâu sau khi bạn viết xong.
- Leverage của doc = giá trị × số người tiếp cận. Distribution quan trọng ngang việc viết; doc không ai đọc có leverage bằng không.
- Chiến lược thực thi: săn pain point lặp lại → viết cho người đọc đang hoảng loạn → đặt đúng chỗ → chủ động phân phối → đo lường và ghi vào brag doc → duy trì → nâng lên meta (đặt chuẩn cho team).
- Luôn gắn con số vào impact khi review. "Giảm ramp-up từ 3 tuần xuống 6 ngày" mạnh gấp nhiều lần "tôi viết một số doc".