Tài liệu kỹ thuật thất bại theo một cách rất cụ thể và rất dễ đoán. Ai đó viết thật nhiều trong hai tuần rảnh rỗi, rồi hệ thống thay đổi, không ai cập nhật lại, và trong vòng một năm tài liệu đó khẳng định những điều sai một cách đầy tự tin. Từ thời điểm ấy nó còn tệ hơn là không có gì, vì người tin vào nó sẽ hành động dựa trên thông tin đã không còn đúng nữa.

Phản ứng thường thấy là thúc mọi người viết nhiều hơn, và điều đó chỉ làm cùng một thất bại đến nhanh hơn. Phản ứng có ích là viết ít đi và chọn kỹ viết cái gì, bởi vì thứ giới hạn bạn không phải là công sức viết. Nó là công sức duy trì.

Phép thử bền vững duy nhất để biết một tài liệu có nên tồn tại hay không: liệu có ai nhận ra khi nó trở nên sai? Một hướng dẫn triển khai được dùng thường xuyên nên lỗi của nó lộ ra ngay lập tức. Một bản mô tả hai mươi trang về một phân hệ chỉ được đọc một lần, và lỗi của nó lộ ra mười tám tháng sau, khi có người hành động theo. Những tài liệu không ai dùng đến thì mục ruỗng trong im lặng, và đó chính là những thứ nên để lại không viết.

Vì sao tài liệu lỗi thời

Có ba cơ chế, và chỉ một trong số đó là sự lười biếng.

Tài liệu sống tách khỏi thứ mà nó mô tả. Sửa mã nguồn không phải là sửa một trang wiki, nên việc giữ cho hai bên khớp nhau phụ thuộc vào trí nhớ của ai đó. Trí nhớ ấy luôn luôn hỏng, và tài liệu càng nằm xa mã nguồn thì nó hỏng càng nhanh.

Tài liệu mô tả cách cài đặt thay vì mô tả ý định. Một tài liệu giải thích một thành phần hiện đang hoạt động ra sao sẽ bị vô hiệu bởi mọi lần tái cấu trúc. Một tài liệu giải thích vì sao thành phần đó tồn tại và nó thỏa mãn ràng buộc nào thì sống sót, vì lý do thay đổi ít hơn nhiều so với mã nguồn.

Không ai sở hữu nó. Tài liệu thuộc về tất cả mọi người thì thực ra không thuộc về ai cả, và không có thời điểm nào mà tính chính xác của nó là việc của một người cụ thể.

Cách chữa suy ra trực tiếp từ nguyên nhân: giữ tài liệu sát mã nguồn, viết ý định thay vì cơ chế, và giao cho mỗi tài liệu một người phụ trách có tên cùng một dịp thực tế để nó được dùng đến.

Tài liệu kỹ thuật đáng duy trì

Bốn tài liệu bao phủ gần hết giá trị. Mọi thứ khác phải tự chứng minh là cần.

Một README giúp bạn chạy được hệ thống. Đây là cái gì, cài ra sao, chạy kiểm thử thế nào, triển khai thế nào. Dùng liên tục nên lỗi lộ ra nhanh. Đây là tài liệu lợi suất cao nhất trong mọi repository, và cũng hay bị bỏ mặc nhất dưới dạng mẫu dự án không ai sửa.

Một bản tổng quan kiến trúc. Các mảnh lớn là gì, chúng giao tiếp ra sao, vì sao được tách rời. Một trang kèm sơ đồ, tả hình dáng chứ không tả chi tiết. Hiếm khi đổi, và trả lời đúng câu hỏi mà người mới, nếu thiếu nó, phải tự dựng lại bằng cách đọc hết.

Các bản ghi quyết định. Ghi chú ngắn lưu lại một quyết định, các phương án đã cân nhắc và lý do chọn. Trong nghề gọi là Architecture Decision Record, viết tắt ADR. Chỉ thêm vào, không cần cập nhật, và ngăn kiểu làm lại tốn kém nhất: bàn lại tệ hại một vấn đề đã chốt vì không ai còn nhớ ràng buộc đã chốt nó.

Runbook cho những thứ hay hỏng. Runbook là quy trình xử lý sự cố: cách chẩn đoán và khắc phục đúng những sự cố bạn đã gặp. Viết ngay sau sự cố, khi còn nóng hổi, và đem ra thử ở lần sau. Runbook chưa ai làm theo thì mới là bản nháp.

Không tài liệu nào ở trên tả mã nguồn hoạt động ra sao. Việc đó đã có mã nguồn, và mọi câu chữ lặp lại nó đều thành nguồn sự thật thứ hai, sớm muộn cũng mâu thuẫn với nguồn thứ nhất.

Viết cho người đang mệt và đang vội

Phần lớn tài liệu kỹ thuật được đọc trong áp lực, bởi một người có câu hỏi rất cụ thể, thường là ngoài giờ làm việc. Hãy viết cho người đọc đó, đừng viết cho một người thong thả.

Trả lời trước, giải thích sau. Người đọc runbook của bạn lúc hai giờ sáng cần thấy câu lệnh trước, lý do sau. Đặt bối cảnh trước câu trả lời là cấu trúc chỉ hợp với người viết và không hợp với ai khác.

Hãy cụ thể. Câu lệnh thật, đường dẫn thật, giá trị ví dụ thật. “Hãy cấu hình các biến môi trường phù hợp” không phải là một chỉ dẫn, nó chỉ là lời mô tả về một chỉ dẫn.

Nói rõ cái gì sẽ hỏng. Các kiểu hỏng hóc và dấu hiệu của chúng thường là phần nội dung giá trị nhất, vì đó đúng là thứ người đọc đang trải qua ngay lúc ấy.

Viết đủ ngắn để nó còn giữ được tính đúng. Mỗi câu là một khoản nợ bảo trì. Một trang bao phủ trường hợp phổ biến và thừa nhận giới hạn của chính nó vẫn hơn một tài liệu bao phủ mọi thứ nhưng sai ở ba chỗ.

Chính sự kỷ luật khiến một trang trở nên đáng trích dẫn với hệ thống truy hồi cũng khiến nó dùng được cho một đồng nghiệp kiệt sức, và đó đúng là điều mà hướng dẫn của chúng tôi về vì sao nội dung xếp hạng nhưng không được trích dẫn muốn nói khi bàn về văn bản công khai.

Giữ cho tài liệu còn sống

Đặt nó trong repository. Một tài liệu đi cùng mã nguồn sẽ được sửa trong cùng một lần review với mã nguồn, và đó là cơ chế duy nhất giữ cho hai bên khớp nhau một cách đáng tin cậy.

Soát nó trong code review. Nếu một thay đổi làm cho tài liệu sai, đó là một nhận xét review như mọi nhận xét khác. Đây là thói quen có đòn bẩy lớn nhất mà bạn có, và nó không tốn gì cả.

Kiểm thử những gì kiểm thử được. Các bước cài đặt chạy được trong pipeline thì không còn là mong ước nữa. Nếu README của bạn khẳng định ba câu lệnh là đủ để có một hệ thống đang chạy, hãy để một job chứng minh điều đó.

Xóa dứt khoát. Một tài liệu sai còn tệ hơn một tài liệu không tồn tại, vì người ta tin vào nó. Khi một thứ đã lỗi thời và không ai sẽ sửa, hãy gỡ nó đi và ghi lại cái gì đã mất theo.

Ghi ngày cho những gì sẽ hết hạn. Bất cứ thứ gì chứa số phiên bản, mức giá hay một phụ thuộc bên ngoài đều nên mang một ngày tháng, để người đọc tự đánh giá được là còn tin được hay không.

Rốt cuộc việc này để làm gì

Tài liệu là cơ chế khiến tri thức thôi phụ thuộc vào từng cá nhân. Đó là toàn bộ lợi ích, và cũng vì thế lý lẽ để viết tài liệu là lý lẽ kinh doanh chứ không phải lý lẽ thẩm mỹ.

Một hệ thống mà chỉ một người biết triển khai thì có thời gian khôi phục đúng bằng mức độ sẵn sàng của người đó. Một thành phần không ai giải thích nổi thì hoặc bị xây lại, hoặc được giữ lại vì mê tín. Cả hai đều xuất hiện thành phát hiện trong thẩm định kỹ thuật, cả hai đều kéo dài quá trình hòa nhập của lập trình viên mới, và cả hai chỉ là một vấn đề khoác hai bộ áo khác nhau.

Mecanik viết những tài liệu này như một phần của việc bàn giao trong mọi dự án, thuộc phạm vi công việc phát triển phần mềm của chúng tôi. Tài liệu cuối cùng được dùng đến gần như luôn ngắn hơn tài liệu đã được đặt hàng.

Câu hỏi thường gặp

Vì sao tài liệu kỹ thuật bị lỗi thời? Vì nó sống tách khỏi mã nguồn nên sự khớp nhau phụ thuộc vào trí nhớ của ai đó; vì nó mô tả cách cài đặt thay vì ý định nên mọi lần tái cấu trúc đều làm nó vô hiệu; và vì không ai sở hữu nó nên tính chính xác của nó không bao giờ là việc cụ thể của một người nào. Giữ tài liệu trong repository và soát nó cùng lúc với các thay đổi mã nguồn xử lý được cả ba nguyên nhân.

Một đội phần mềm nên duy trì những tài liệu nào? Bốn thứ bao phủ gần hết giá trị: một README giúp hệ thống chạy được, một bản tổng quan kiến trúc dài một trang giải thích hình dáng và lý do, các bản ghi quyết định chỉ thêm vào để lưu lại vì sao đã chọn như vậy, và runbook cho những sự cố bạn đã thực sự gặp. Phần mô tả mã nguồn hoạt động ra sao không nằm trong danh sách này.

Bản ghi quyết định là gì? Là một ghi chú ngắn lưu lại một quyết định, các phương án đã cân nhắc và lý do chọn. Vì nó ghi lại một thời điểm chứ không phải trạng thái hiện tại nên nó không bao giờ cần cập nhật, và nó ngăn việc những vấn đề đã chốt bị đem ra tranh luận lại một cách tệ hại bởi những người không còn nhớ ràng buộc đã chốt chúng.

Nên viết tài liệu kỹ thuật như thế nào? Viết cho một người đang mệt, đang chịu áp lực và chỉ tìm đúng một thứ. Trả lời trước rồi giải thích sau, dùng câu lệnh thật và đường dẫn thật thay vì mô tả về chúng, nói rõ cái gì sẽ hỏng và nó trông ra sao, và viết đủ ngắn để nội dung còn giữ được tính đúng.

Có nên xóa tài liệu đã lỗi thời không? Có, nếu không ai sẽ sửa nó. Một tài liệu sai còn tệ hơn một tài liệu không tồn tại, vì người đọc tin nó và hành động theo. Hãy xóa và ghi lại cái gì đã mất, đồng thời ghi ngày cho mọi thứ chứa số phiên bản, mức giá hay một phụ thuộc bên ngoài để người đọc tự đánh giá được.