Viết design doc để đội kỹ thuật của khách duyệt trước khi bạn code

Thử hình dung bạn là FDE vừa được cử sang công ty khách. Bạn code trong hệ thống của người khác, đội kỹ thuật của họ gần như chắc chắn có tiếng nói cuối cùng, và một hiểu lầm về phạm vi có thể đốt mất vài tuần.

Ở Google, design doc được viết trước khi code và được mô tả là những tài liệu “khá thoải mái” về hình thức. Ấy vậy mà chính loại tài liệu xuề xòa này lại là chỗ lỗi thiết kế bị phát hiện sớm, khi việc sửa còn rẻ.

Design doc còn là công cụ để đạt đồng thuận về thiết kế trong tổ chức. Ở site khách, đó là cách bạn thống nhất với họ trước khi viết dòng code đầu tiên.

Hướng dẫn dưới đây đi qua bảy bước, áp vào một tình huống giả định. Kết quả là một design doc dài 2-3 trang mà bạn có thể gửi cho tech lead phía khách ngay trong tuần.

Bạn sẽ viết gì, và cần chuẩn bị gì?

Tình huống giả định thế này: bạn được cử sang một công ty logistics để triển khai một agent đọc ticket hỗ trợ và gán nhãn phân loại. Agent phải tích hợp với hệ thống ticket nội bộ của họ, và đội platform phía khách sẽ là người duyệt.

Bạn cần ba thứ: ghi chú từ các buổi customer discovery, sơ đồ thô về hệ thống hiện tại của khách, và một công cụ soạn thảo có comment theo lề như Google Docs. Không cần gì cao siêu hơn.

Bước 1: Hỏi xem giải pháp có mơ hồ không

Cách Google tiếp cận design doc xoay quanh một câu hỏi: giải pháp cho bài toán thiết kế có mơ hồ hay không. Nếu ai cũng biết phải làm gì thì viết doc chẳng thêm được bao nhiêu giá trị. Angela Zhang bổ sung một mốc tham khảo: việc có thể tốn từ 1 engineer-month trở lên thì nên có design doc.

Hãy coi mốc thời gian đó là tín hiệu phụ; điều kiện quyết định vẫn là độ mơ hồ. Áp vào ví dụ, câu hỏi mơ hồ nằm ở chỗ agent nên ghi nhãn thẳng vào database ticket hay đi qua một hàng đợi để đội platform kiểm soát.

Có hai lựa chọn hợp lý, và chúng ảnh hưởng tới hệ thống của khách, thế là đủ lý do để viết doc.

Kiểm tra: bạn viết được câu hỏi thiết kế chính trong đúng một câu. Nếu không viết được thì bạn chưa hiểu bài toán, và nên quay lại discovery.

Bước 2: Mượn khung có sẵn, cắt cho vừa

The Pragmatic Engineer đã tổng hợp các mẫu công khai của Google, Uber, Stedi và Monzo, kèm lời khuyên là lấy những phần thấy hợp với mình. Dưới đây là một khung rút gọn cho việc ở site khách. Đây là bản đơn giản hóa, không phải mẫu chính thức của công ty nào.

# [Tên dự án] — Design Doc
Tác giả · Reviewer phía khách · Hạn góp ý · Trạng thái

## Hiện trạng hệ thống (1 đoạn)
## Goals
## Non-goals
## Thiết kế đề xuất (sơ đồ + luồng dữ liệu)
## Các phương án đã cân nhắc và trade-off
## Câu hỏi mở cần khách trả lời

Dòng “Hạn góp ý” và mục “Câu hỏi mở” là hai phần thêm vào riêng cho bối cảnh FDE. Phần đầu khiến việc duyệt có thời hạn rõ ràng. Phần sau biến những gì bạn chưa biết thành việc mà khách phải trả lời.

Bước 3: Non-goals là nơi bạn khoanh phạm vi

Theo cách Google định nghĩa, non-goals là những thứ hoàn toàn có thể là mục tiêu nhưng được chủ động loại ra. Chữ “hoàn toàn có thể” là mấu chốt. Ghi “không xây lại hệ thống ticket” thì vô ích, vì chẳng ai đòi việc đó.

Goals	Non-goals
Agent gán nhãn phân loại cho ticket mới	Agent tự trả lời khách hàng
Đội platform xem lại được mọi nhãn	Gán nhãn lại toàn bộ ticket cũ
Nhãn sai có thể sửa tay	Thay đổi quy trình làm việc của đội CSKH

Trong tình huống giả định này, cả ba non-goal bên phải đều là thứ một quản lý phía khách rất có thể sẽ hỏi tới giữa chừng dự án. Viết chúng ra ngay từ đầu nghĩa là bạn đã thương lượng xong trước khi có tranh cãi.

Kiểm tra: đưa danh sách non-goals cho một người không thuộc dự án. Nếu họ phản ứng “ơ, cái này không làm à?” với ít nhất một dòng thì bạn đã viết đúng.

Bước 4: Viết trade-off, đừng chỉ viết đáp án

Theo mô tả về cách làm ở Google, design doc tập trung vào chiến lược ở mức cao và các trade-off. Angela Zhang thì viết rằng mục tiêu chính của design doc là buộc bạn nghĩ cho kỹ thiết kế và thu góp ý từ người khác, chứ không phải để lưu hồ sơ.

Trong ví dụ, hãy đặt hai phương án cạnh nhau. Ghi thẳng vào database thì nhanh và ít thành phần hơn, nhưng agent có quyền ghi vào dữ liệu lõi của khách. Đi qua hàng đợi thì chậm hơn và thêm một thứ phải vận hành, đổi lại đội platform giữ được quyền kiểm soát. Bạn đề xuất một phương án và nói rõ lý do.

Đội kỹ thuật phía khách sống với hệ thống đó mỗi ngày, nên nhiều khả năng họ thấy những rủi ro mà bạn chưa thấy. Viết trade-off ra là mời họ chỉ ra điều đó, đúng vào lúc sửa vẫn còn rẻ.

Bước 5: Một reviewer sơ bộ trước, cả đội sau

Một bài trên blog Refactoring English khuyên đừng gửi bản nháp cho tất cả mọi người cùng lúc. Hãy tìm một reviewer sơ bộ trước. Ở site khách, người đó lý tưởng là một đồng nghiệp trong team bạn hoặc một kỹ sư phía khách mà bạn đã làm việc cùng.

Lý do rất thực tế. Bản nháp đầu nào cũng có lỗ hổng hiển nhiên. Để cả đội platform của khách thấy những lỗ hổng đó thì bạn phí mất ấn tượng đầu tiên, trong khi một người là đủ để bắt chúng.

Bước 6: Gửi đi, kèm thời hạn

Tác giả bài viết trên Refactoring English luôn cho người duyệt ít nhất hai ngày làm việc để đọc một design doc. Hãy ghi hạn này ngay trên đầu doc và trong tin nhắn gửi đi. Ví dụ: gửi sáng thứ Hai, hạn góp ý hết ngày thứ Tư.

Kiểm tra: tin nhắn của bạn nêu rõ ba thứ, gồm doc ở đâu, bạn cần họ quyết định điều gì, và hạn là khi nào.

Bước 7: Trả lời từng comment rồi mới đóng

Khi comment bắt đầu đổ về, hãy trả lời từng ghi chú bên lề và chỉ resolve thread khi bạn chắc mình đã xử lý xong ý đó. Đừng resolve chỉ để doc trông gọn. Người viết comment dễ nhận ra, và lần sau họ có thể chẳng buồn góp ý nữa.

Với những quyết định mà comment không thể chốt, hãy ghi lại thành một quyết định có người chịu trách nhiệm. Stedi xem loại ghi chép quyết định như một cơ chế ép các bên phải thống nhất về một quyết định cần đưa ra. Trong ví dụ, đó chính là bằng chứng cho thấy đội platform đã đồng ý với phương án hàng đợi.

Vì sao doc của bạn bị lờ đi?

Lỗi phổ biến nhất là viết doc cho một việc chẳng có gì mơ hồ, khiến người duyệt thấy phí thời gian và lần sau bỏ qua doc của bạn. Lỗi thứ hai là thiếu non-goals, hoặc viết những non-goal mà chẳng ai đòi.

Lỗi thứ ba là gửi bản nháp thô cho cả nhóm mà không ghi hạn góp ý, rồi chờ mãi không thấy ai trả lời.

Kỹ năng này trông thế nào trong hồ sơ của bạn?

Khi đọc JD của một vị trí FDE, hãy để ý những cụm kiểu như “làm việc trực tiếp với đội kỹ thuật của khách” hay “dẫn dắt technical alignment”. Đó là chỗ kỹ năng này được kiểm tra. Trong CV, đừng viết “có kỹ năng giao tiếp tốt”. Hãy viết rằng bạn đã soạn design doc, nêu rõ ai duyệt và quyết định nào được chốt nhờ nó.

Nếu chưa có khách hàng thật, hãy luyện ngay ở công ty hiện tại: chọn một task có giải pháp còn mơ hồ, viết doc theo bảy bước trên rồi gửi cho một team khác duyệt. Một team khác trong cùng công ty cũng nhìn hệ thống từ bên ngoài, giống như khách hàng.

Bản design doc tốt nhất không phải bản được khen hay. Đó là bản mà đội kỹ thuật của khách đã sửa trước khi bạn kịp viết một dòng code nào.