Cách viết một tài liệu thiết kế phần mềm hiệu quả

Một tài liệu thiết kế tốt có thể giúp bạn tiết kiệm hàng năm trời phát triển. Việc viết tài liệu thiết kế buộc bạn phải suy nghĩ thấu đáo về các quyết định quan trọng trước khi lãng phí thời gian vào một hướng triển khai sai lầm. Đây cũng là cách tốt nhất để phối hợp các quyết định thiết kế giữa các thành viên trong nhóm và với các nhóm đối tác.

Tác giả bài viết gốc đã viết tài liệu thiết kế khi làm việc tại Google, Microsoft và trong các công ty riêng của mình. Chi tiết có thể khác nhau, nhưng các nguyên tắc cốt lõi vẫn giữ nguyên. Một tài liệu thiết kế trình bày rõ những bài toán khó mà bạn đang giải quyết và giúp đồng nghiệp đưa ra phản hồi cho bạn.

Khi nào bạn nên viết tài liệu thiết kế?

Dự án càng phức tạp hoặc càng nhiều rủi ro thì việc viết tài liệu thiết kế càng có giá trị. Hãy cân nhắc những câu hỏi sau:

• Có nhiều người cùng phối hợp để triển khai thiết kế không?
• Dự án có mất hơn ba tháng làm việc toàn thời gian không?
• Bản triển khai có chạy trong môi trường production nhiều năm không?
• Dự án có liên quan đến phối hợp liên nhóm không?
• Mục tiêu và yêu cầu của dự án có mơ hồ không?
• Có rủi ro nghiêm trọng nào bạn có thể ngăn chặn ngay từ giai đoạn thiết kế không (ví dụ: lỗ hổng bảo mật, rủi ro pháp lý)?

Nếu bạn trả lời "có" cho bất kỳ câu hỏi nào ở trên, rất có thể việc viết tài liệu thiết kế là đáng công. Nếu bạn trả lời "có" cho từ hai câu hỏi trở lên, tài liệu thiết kế gần như chắc chắn sẽ mang lại giá trị tương xứng.

Nên đầu tư bao nhiêu công sức?

Một tài liệu thiết kế có thể chỉ là một trang đơn giản, hoặc cũng có thể là một văn bản dài 50 trang cần sự phê duyệt của năm nhóm khác nhau. Bạn cần quyết định mức độ chi tiết nào là hợp lý.

Không có quy tắc chung nào quy định bạn nên dành bao nhiêu thời gian cho tài liệu thiết kế, cũng giống như không có quy tắc nào quy định bạn nên kiểm thử code bao nhiêu. Mức đầu tư phù hợp phụ thuộc vào mục tiêu, rủi ro, thời hạn và văn hóa của nhóm bạn. Đôi khi, số công sức đúng đắn dành cho tài liệu thiết kế là bằng không.

Điều gì thuộc về tài liệu thiết kế?

Nếu bạn đặc tả mọi chi tiết có thể trong tài liệu thiết kế, về cơ bản bạn đã viết xong phần triển khai ngay trong giai đoạn thiết kế. Điều đó sẽ phá hỏng toàn bộ mục đích của tài liệu thiết kế.

Theo nguyên tắc chung, bạn có thể tự hỏi một câu đơn giản để quyết định liệu một quyết định nào đó có thuộc về tài liệu thiết kế hay không: cái giá phải trả nếu chọn sai là bao nhiêu?

Không phải mọi quyết định thiết kế đều quan trọng như nhau. Một số lựa chọn mang tính lâu dài hơn những lựa chọn khác.

Ví dụ, nếu bạn xây dựng một ứng dụng web bằng C++ và nhận ra sau 200 nghìn dòng code rằng Ruby on Rails mới là lựa chọn đúng đắn, bạn đã bị kẹt. Việc viết lại từ đầu sẽ không bao giờ khả thi, và ngay cả khi bạn viết được code mới bằng Rails, bạn vẫn phải bảo trì code bằng hai ngôn ngữ hoàn toàn khác biệt.

Sơ đồ kiến trúc minh họa cho một ứng dụng web đơn giản

Ngược lại, những quyết định thiết kế khác lại rất nhỏ nhặt. Ví dụ, nếu ứng dụng hiển thị danh sách 100 bài viết, bạn nên cho tất cả hiện ra cùng lúc? Hay người dùng chỉ thấy 25 bài và bấm "Tải thêm" để xem 25 bài tiếp theo?

Điều đó không quan trọng. Nút "Tải thêm" không phải là vấn đề ở tầm thiết kế. Nếu bạn chọn một giải pháp và phản hồi từ người dùng cho thấy bạn đã sai, bạn có thể sửa trong vài giờ. Bạn không cần trình bày chi tiết toàn bộ quá trình suy nghĩ trong tài liệu thiết kế, và chắc chắn không nên lãng phí các vòng đánh giá để tranh cãi về nó.

Các thành phần của một tài liệu thiết kế

Dưới đây là các mục thường gặp trong tài liệu thiết kế. Bạn thường không cần đủ tất cả các mục cho mọi tài liệu. Hãy chọn tập hợp con phù hợp với bạn.

Tiêu đề

Điều đầu tiên dự án của bạn cần là một tiêu đề. Đây là cách mọi người sẽ nhắc đến dự án trong các cuộc trò chuyện, nên hãy hướng tới một cái tên ngắn gọn, dễ phân biệt và gợi hình.

Ví dụ, nếu bạn đang thêm một lớp cache giữa máy chủ ứng dụng và máy chủ cơ sở dữ liệu, RecencyBank là một cái tên hay. Nó dễ nói và mô tả được mục đích của dự án. Một cái tên tồi sẽ là "Dự án Ngựa Bạc Bay" vì nó dài dòng và vô nghĩa.

Siêu dữ liệu

Nhàm chán nhưng hữu ích, phần siêu dữ liệu giúp người đọc hiểu bối cảnh cơ bản của tài liệu:

• Tác giả là ai? (tên + địa chỉ email)
• Bạn tạo tài liệu khi nào?
• URL chính thức là gì? Đặc biệt quan trọng nếu tổ chức của bạn dùng các liên kết rút gọn như http://go/recency-bank
• Ai đã phê duyệt tài liệu này và khi nào? Trong trường hợp tài liệu cần sự chấp thuận của đồng nghiệp hoặc đối tác.

Mục tiêu

Mục tiêu là phần giải thích mục đích dự án trong một câu. Nó nên xuất hiện ở trang đầu tiên của tài liệu bằng ngôn ngữ đơn giản mà bất kỳ bên liên quan nào cũng hiểu.

Cải thiện hiệu năng ứng dụng bằng cách thêm lớp cache giữa máy chủ web Trogdor và cơ sở dữ liệu Postgres.

Bối cảnh

Phần bối cảnh giải thích lý do và động lực của dự án. Nó nên trả lời các câu hỏi:

• Tại sao nhóm lại thực hiện dự án này?
• Dự án này giải quyết vấn đề gì?
• Trước đây đã có nỗ lực nào giải quyết vấn đề này chưa?

Hãy hình dung điều bạn sẽ nói với một đồng nghiệp hoặc nhóm đối tác trước khi họ đọc tài liệu thiết kế của bạn. Sau đó nhận ra rằng một số người đọc sẽ xem tài liệu trước khi nghe bất kỳ lời giải thích nào từ bạn, vì vậy những gì họ cần hiểu phải nằm ở trang đầu tiên.

Tài liệu liên quan

Nếu dự án này kết nối với các tài liệu khác, hãy giúp người đọc dễ dàng tìm thấy chúng. Bao gồm liên kết đến:

• Tài liệu từ quản lý chương trình hoặc nhóm kiểm thử (ví dụ: kế hoạch kiểm thử, đặc tả chức năng)
• Tài liệu thiết kế cho các hệ thống liên quan
• Tài liệu thiết kế cho các phiên bản trước của dự án này

Mục tiêu (Goals)

Phần mục tiêu mô tả các mục tiêu cấp cao của bạn cho dự án. Nó nên kết nối logic với phần bối cảnh và giải thích thế giới sẽ trông như thế nào sau khi bạn hoàn thành triển khai.

Tránh đặt mục tiêu theo các chi tiết triển khai nội bộ. Mục tiêu của bạn nên truyền đạt dự án mang lại lợi ích gì cho người dùng, nhóm hoặc công ty.

• Tồi: Đặt mục tiêu theo chi tiết triển khai nội bộ — "Thêm Kubernetes vào hạ tầng của chúng ta."
• Tốt: Đặt mục tiêu theo tác động — "Giảm thiểu sự cố gián đoạn liên quan đến việc triển khai phiên bản ứng dụng mới."

Phi mục tiêu (Non-goals)

Trong khi phần mục tiêu xác định điều gì nằm trong phạm vi dự án, phần phi mục tiêu phân định rõ điều gì nằm ngoài phạm vi.

Có mục tiêu nào mà người đọc có thể nhầm tưởng là thuộc phạm vi dự án của bạn không? Nếu có, hãy thêm chúng như những phi mục tiêu rõ ràng.

Kịch bản

Nếu mục tiêu của bạn là điều gì đó như "Thêm nút 'Chia sẻ dưới dạng URL' vào biểu đồ", người đọc có thể không hiểu điều đó trông như thế nào trong thực tế.

Phần kịch bản cho phép bạn vẽ ra bức tranh cho người đọc về cách hệ thống đã hoàn thiện của bạn hoạt động trong thế giới thực.

Sơ đồ

Sơ đồ cực kỳ có giá trị, dù thoạt nhìn có vẻ không như vậy.

Với tư cách là tác giả thiết kế, bạn hiểu một cách trực giác các mảnh ghép trong kế hoạch của mình khớp với nhau như thế nào. Bạn có thể nhìn thấy kiến trúc trong đầu. Những người đánh giá thì không có hình dung này, nên cách nhanh nhất để họ thấy được là vẽ cho họ một bức tranh.

Nếu bạn không chắc điều gì thuộc về một sơ đồ, hãy nghĩ đến những câu hỏi sau:

• Dữ liệu chảy qua hệ thống của bạn như thế nào?
• Các thành phần khác nhau của hệ thống khớp với nhau ra sao?
• Hệ thống của bạn tương tác với các phụ thuộc và máy khách phía sau như thế nào?
• Hệ thống của bạn định nghĩa những giao thức giao tiếp nào?

Hãy chọn một công cụ vẽ sơ đồ linh hoạt trong việc chỉnh sửa. Tôi từng thấy các lập trình viên tạo một sơ đồ đẹp trên bảng trắng rồi chụp ảnh lại cho tài liệu thiết kế. Bản nháp đầu tiên trông tuyệt vời, nhưng sau đó họ bị kẹt với sơ đồ đó mãi mãi vì không thể chỉnh sửa ảnh mà không vẽ lại từ đầu.

Excalidraw, draw.io và Google Drawings là những công cụ vẽ sơ đồ phổ biến hỗ trợ việc chỉnh sửa. Ngoài ra còn có các ngôn ngữ như Mermaid, D2 và Graphviz cho phép bạn tạo sơ đồ bằng lập trình. Tôi đã có trải nghiệm tốt khi dùng LLM để tạo code vẽ sơ đồ cho mình. Hãy nhớ liên kết đến bản vẽ gốc hoặc code nguồn để đồng nghiệp có cách tái tạo sơ đồ.

Bảng thuật ngữ

Bảng thuật ngữ định nghĩa các thuật ngữ mà người đọc có thể không nhận ra.

Hãy suy nghĩ kỹ về những người đọc tiềm năng của tài liệu, đặc biệt là các thành viên mới trong nhóm và những người ngoài nhóm trực tiếp của bạn. Liệu những người đọc đó có hiểu tên các công cụ hoặc hệ thống nội bộ mà tài liệu của bạn đề cập không?

Khi có thể, hãy dùng các thuật ngữ mà khán giả của bạn nhận ra mà không cần tra bảng thuật ngữ. Định nghĩa một thuật ngữ trong bảng thuật ngữ vẫn tốt hơn là không định nghĩa gì cả, nhưng giải pháp tốt nhất là dùng thuật ngữ dễ nhận biết hoặc định nghĩa ngay trong dòng để người đọc không phải nhảy qua nhảy lại trong tài liệu.

Ràng buộc

Nếu có những ràng buộc lớn do ngân sách, khách hàng, hạ tầng hoặc các phụ thuộc áp đặt lên thiết kế của bạn, hãy giải thích các ràng buộc đó để người đọc hiểu bối cảnh của các lựa chọn thiết kế.

Mục tiêu cấp độ dịch vụ (SLO)

SLO tạo ra một chỉ số đo lường được, khách quan cho hiệu năng hệ thống của bạn. Bạn có thể đã nghe đến thuật ngữ thỏa thuận cấp độ dịch vụ (SLA). SLA chỉ là SLO cộng thêm các hình phạt tài chính khi không đạt yêu cầu.

Trong nội bộ một công ty, bạn thường không phạt tiền đồng nghiệp vì sai sót. Vì vậy, tài liệu thiết kế định nghĩa SLO thay vì SLA.

Quản lý của bạn có thể nói rằng ứng dụng của bạn phải "hoạt động hiệu quả trên di động", nhưng điều đó rất mơ hồ. Ý niệm về "hiệu quả" của quản lý bạn có thể là hoàn thành trong 3 giây, trong khi của bạn là 5 giây. SLO biến những kỳ vọng mơ hồ thành các mục tiêu đo lường được.

Dòng thời gian

Phần dòng thời gian chia dự án thành các cột mốc. Nó xác định khi nào bạn sẽ bàn giao kết quả cho các bên liên quan.

Hãy chọn các cột mốc tạo ra những sản phẩm hữu ích cho các bên liên quan. Ví dụ, bắt đầu bằng một giao diện hiển thị dữ liệu giả và cho khách hàng xem trước. Nếu hóa ra bạn hiểu sai yêu cầu của khách hàng, dữ liệu giả cho phép bạn phát hiện sớm thay vì sau khi đã triển khai xong toàn bộ hệ thống để nạp dữ liệu production vào giao diện.

Giao diện

Dự án của bạn tồn tại để phục vụ con người hoặc các hệ thống phần mềm khác, vậy những tương tác đó trông như thế nào?

• Với hệ thống đồ họa: giao diện người dùng là gì? Chỉ cần phác thảo đơn giản, đừng sa đà vào các lựa chọn UI chi tiết.
• Với giao diện phần mềm: ngữ nghĩa API hoặc CLI là gì?
• Với giao diện dựa trên tệp: định dạng tệp là gì?

Phụ thuộc / hạ tầng

Phần phụ thuộc nên trả lời các câu hỏi như:

• Bạn sẽ dùng (những) ngôn ngữ lập trình nào?
• Code chạy trên phần cứng hoặc dịch vụ nào?
• Dữ liệu lâu dài sẽ nằm ở đâu?

Dễ bỏ qua phần này, nhưng các quyết định về ngôn ngữ, thư viện và hạ tầng có tác động lớn đến độ phức tạp và chi phí bảo trì lâu dài của hệ thống.

Hãy suy nghĩ sâu về những phụ thuộc sẽ khó thay đổi sau khi triển khai. Đừng lo lắng quá về những thứ dễ thay thế. Rất khó thay đổi ngôn ngữ hoặc backend lưu trữ, nhưng nếu bạn không hài lòng với dịch vụ bên thứ ba dùng để gửi email, bạn có thể thay nó trong một buổi chiều.

Bảo mật

Để xây dựng phần mềm an toàn, lập trình viên phải tích hợp bảo mật vào toàn bộ vòng đời phát triển phần mềm, bắt đầu từ giai đoạn thiết kế.

Phần bảo mật nên trả lời các câu hỏi như:

• Bạn đã xem xét những mối đe dọa nào? Ví dụ, điều gì xảy ra nếu kẻ tấn công thử mọi mật khẩu có thể? Nếu người dùng tải lên một tệp PDF nhiễm mã độc thì sao?
• Bề mặt tấn công của hệ thống này là gì? Tức là, nó xử lý dữ liệu có khả năng độc hại ở đâu?
• Các ranh giới tin cậy nằm ở đâu? Dữ liệu chảy từ hệ thống ít đặc quyền sang hệ thống nhiều đặc quyền hơn tại thời điểm nào?

Ngay cả khi bạn cho rằng các mối đe dọa bảo mật khó xảy ra hoặc không liên quan trong hệ thống của mình, việc ghi lại lý do vẫn hữu ích. Lời giải thích của bạn có thể khiến người đánh giá nhận ra những mối đe dọa mà bạn đã bỏ sót.

Quyền riêng tư

Phần quyền riêng tư là cơ hội để suy nghĩ kỹ về dữ liệu nhạy cảm mà hệ thống xử lý và những biện pháp bảo vệ bạn sẽ áp dụng để giữ an toàn. Nó nên trả lời các câu hỏi:

• Hệ thống của bạn xử lý dữ liệu nhạy cảm nào?
• Bạn sẽ lưu giữ nó trong bao lâu?
• Ai sẽ có quyền truy cập nó?
• Bạn sẽ bảo vệ nó như thế nào? Ví dụ, dữ liệu sẽ được mã hóa khi lưu trữ và khi truyền tải không?

Cân nhắc pháp lý

Nếu hệ thống của bạn hoạt động trong lĩnh vực được quản lý chặt chẽ như tài chính hoặc y tế, phần pháp lý giúp bạn tuân thủ các luật liên quan.

Ngay cả ngoài các lĩnh vực được quản lý, hãy nghĩ xem liệu hệ thống của bạn có thể vi phạm pháp luật nếu mọi thứ đi chệch hướng không. Giải thích cách bạn sẽ tránh các vi phạm pháp lý có thể gây rủi ro cho công ty hoặc khách hàng.

Nếu bạn phát hành code theo giấy phép mã nguồn mở, hãy xác định bạn đã chọn giấy phép nào và vì sao.

Ghi log

Log có thể cực kỳ có giá trị khi bạn điều tra một lỗi, vấn đề hiệu năng hoặc sự cố bảo mật. Nếu bạn thiết kế để ghi log hiệu quả, bạn sẽ giúp việc bảo trì hệ thống lâu dài trở nên dễ dàng hơn.

Khi nghĩ về ghi log, hãy cân nhắc các câu hỏi sau:

• Dịch vụ ghi log những sự kiện quan trọng nào?
• Có các mức log khác nhau không? Ví dụ: thông tin, cảnh báo, lỗi, nghiêm trọng.
• Hệ thống lưu log ở đâu?
• Bạn giữ log trong bao lâu?
• Ai có quyền truy cập log?
• Có dữ liệu nhạy cảm nào bạn phải giữ ngoài log không?

Vấn đề mở

Khi viết tài liệu thiết kế, bạn có thể sẽ gặp ít nhất một trong các tình huống sau:

• Có lỗ hổng trong thiết kế của bạn, nhưng bạn chưa biết cách giải quyết.
• Có khoảng trống trong thiết kế, nhưng bạn cần thu thập thêm thông tin để lấp đầy.
• Bạn phân vân giữa nhiều giải pháp.

Hãy tạo một phần phụ lục trong tài liệu thiết kế gọi là "Vấn đề mở" để ghi lại các vấn đề còn tồn đọng. Mỗi mục trong phần vấn đề mở nên giải thích:

• Vấn đề nào cần làm thêm?
• Bạn thấy những lựa chọn nào để giải quyết vấn đề?
• Bước tiếp theo ngay lập tức để giải quyết vấn đề là gì?

Vấn đề đã giải quyết

Khi bạn giải quyết một vấn đề mở, hãy tóm tắt quyết định và chuyển nó từ phần "Vấn đề mở" sang phần "Vấn đề đã giải quyết" trong tài liệu thiết kế. Giữ lại toàn bộ thảo luận cho hậu thế.

Các phương án thay thế đã cân nhắc

Nếu bạn dự đoán người đọc sẽ hỏi "Tại sao bạn không làm X?", việc trả lời chủ động trong phần "các phương án thay thế đã cân nhắc" sẽ rất hữu ích. Phần này cũng là nơi bạn có thể giải thích các lựa chọn bạn đã loại bỏ, đặc biệt nếu ban đầu chúng có vẻ hấp dẫn hoặc bạn đã nghiên cứu chúng kỹ lưỡng.

Tôi biết một số lập trình viên dành hàng giờ để ghi chép tỉ mỉ mọi ý tưởng thiết kế bị loại bỏ, nhưng tôi cho rằng đó là quá mức cần thiết. Với cả tư cách người đọc lẫn người viết, tất cả những gì tôi cần trong phần phương án thay thế là vài dòng ngắn gọn mô tả các lựa chọn mạnh và lý do chúng không hiệu quả.

Đưa tài liệu thiết kế qua vòng đánh giá

Sau khi hoàn thành tài liệu thiết kế, bước tiếp theo là chia sẻ nó với nhóm và thu thập phản hồi.

Mục tiêu là khơi gợi những phản hồi thiết kế hữu ích giúp dự án tiến lên, thay vì để nó đình trệ vì những tranh cãi và nhầm lẫn. Hãy đặt câu hỏi cụ thể cho người đánh giá về những điểm bạn chưa chắc chắn, và chỉ định rõ thời hạn phản hồi để vòng đánh giá không kéo dài vô tận.

Kết luận

Tài liệu thiết kế không phải là thủ tục hành chính rườm rà, mà là công cụ tư duy giúp bạn tránh những sai lầm tốn kém. Hãy đầu tư đúng mức dựa trên rủi ro và độ phức tạp của dự án, tập trung vào những quyết định khó thay đổi, và đừng ngại dành thời gian cho những phần như sơ đồ và kịch bản — những thứ giúp đồng nghiệp của bạn hiểu đúng ý tưởng của bạn ngay từ đầu.