Tài liệu tồn tại lâu dài sau khi bạn vắng mặt sẽ phục vụ người nhận bàn giao, người kiểm toán, và chính Kiến trúc sư khi quay trở lại

Vòng phản hồi (feedback loop) giữ cho hệ thống khỏe mạnh trong khi bạn đang vận hành nó. Tài liệu hóa (Documentation) là thứ giữ cho hệ thống tiếp tục hoạt động sau khi bạn rời đi.

Chủ đề này biến toàn bộ bản thiết kế thành tài liệu sống lâu hơn một đợt bàn giao và làm hài lòng một người kiểm duyệt tuân thủ. Hoặc là bản thiết kế tự mang theo lập luận của nó vào đợt bàn giao đó, hoặc là sự lập luận đó sẽ biến mất ngay thời điểm bạn rời đi. Xét theo vòng đời dự án, tài liệu hóa chính là giai đoạn Bàn giao (Handoff) trong vòng đời triển khai.

Một bộ tài liệu phục vụ Ba người đọc, và nếu chỉ phục vụ một người thì nó vẫn chưa hoàn chỉnh

Tài liệu kiến trúc phục vụ 3 đối tượng người đọc:

1. Kỹ sư tiếp quản (Inheriting engineer): Người tiếp quản một bản triển khai mà họ không hề tham gia xây dựng từ đầu.

2. Người kiểm toán (Auditor): Người tìm đến sau này để tìm kiếm bằng chứng cho thấy một cơ chế kiểm soát cụ thể đang chạy thực tế và được giải trình rõ ràng.

3. Kiến trúc sư quay trở lại (Returning architect): Thường chính là bạn, quay trở lại sau nhiều tháng và không còn nhớ gì về các buổi họp thiết kế ban đầu.

Một tài liệu chỉ được xây dựng cho một trong những người đọc này mà bỏ qua những người khác thì vẫn chưa hoàn chỉnh ngay cả khi nó rất chi tiết.

Chi tiết Yêu cầu cho từng Đối tượng Người đọc

1. Đối với Người nhận bàn giao: Các phương án thay thế bị từ chối cũng quan trọng không kém các quyết định được đưa ra

Đối với bất kỳ ai tiếp quản hệ thống, tài liệu phải mang theo: các quyết định đã được đưa ra, các phương án thay thế bị từ chối, và lý do tại sao từng sự từ chối đó lại diễn ra.

Một bản thiết kế được bàn giao mà không có các phương án bị từ chối thì người không có mặt trong phòng họp không thể hiểu được. Họ sẽ đảo ngược một quyết định đúng vì một lý do sai, hoặc bảo vệ một quyết định sai vì họ không thể phân biệt được nó đang giải quyết sự đánh đổi nào. Các tùy chọn bị từ chối giải thích lý do tại sao bản thiết kế lại có hình dáng như hiện tại.

2. Đối với Người kiểm duyệt tuân thủ: Bằng chứng quan trọng hơn các lời khẳng định

Đối với người kiểm duyệt tuân thủ, tài liệu phải mang theo: từng nghĩa vụ quy định, cơ chế kiểm soát kỹ thuật đáp ứng nó, người sở hữu cơ chế kiểm soát đó, và tài sản minh chứng (evidence artifact) chứng minh cơ chế kiểm soát đang vận hành.

Đây chính là Sổ đăng ký kiểm soát (control register) của bản triển khai bị kiểm soát, được đưa vào tài liệu sống quản trị đời sống vận hành thực tế của bản triển khai. Người kiểm toán không chấp nhận những lời khẳng định suông. Họ yêu cầu bằng chứng, nghĩa là một phát biểu "cơ chế kiểm soát có tồn tại" là chưa đủ.

3. Đối với Kiến trúc sư quay trở lại: Có thể định hướng mà không cần một buổi tóm tắt

Đối với Kiến trúc sư quay trở lại sau nhiều tháng, tài liệu phải tự đứng vững được trên đôi chân của nó:

• Các quyết định phải có ngày tháng rõ ràng.

• Các giả định được dán nhãn rõ ràng là "giả định" thay vì nhúng vào như những sự thật.

• Các mục chưa giải quyết phải có người sở hữu và tiêu chí giải quyết.

Bài kiểm thử thực tế: Sau khi đọc tài liệu, liệu một Kiến trúc sư có năng lực không có mặt tại các buổi họp thiết kế ban đầu có thể thực hiện một thay đổi an toàn cho hệ thống hay không? Nếu câu trả lời là KHÔNG, tài liệu đó chưa hoàn chỉnh.

Danh sách kiểm tra tính đầy đủ của Tài liệu (Documentation completeness checklist)

Chi phí · Độ phức tạp · Rủi ro

• Chi phí (Cost): Việc viết ra lý do lập luận và bằng chứng tại thời điểm thiết kế tốn thời gian. Việc tái tạo lại nó sau này từ các luồng email, hoặc thất bại trong việc tái tạo, sẽ phải trả giá bằng một sự đảo ngược sai lầm trên môi trường production.

• Độ phức tạp (Complexity): Kỷ luật ở đây là ghi lại LÝ DO TẠI SAO chứ không chỉ ghi cái GÌ, và dán nhãn các giả định là giả định — việc này rất dễ bị bỏ qua khi sự lập luận cảm thấy quá rõ ràng đối với người vừa trải qua nó.

• Rủi ro (Risk): Thất bại đắt giá nhất là người kế nhiệm đảo ngược một quyết định chịu tải (load-bearing decision) vì lý do lập luận chưa bao giờ được tài liệu hóa, làm xuất hiện trở lại một vi phạm ràng buộc mà bản thiết kế ban đầu đã giải quyết xong.