Bí quyết viết tài liệu thiết kế phần mềm hiệu quả từ kỹ sư Google và Microsoft

Một bản design doc tốt có thể giúp bạn tiết kiệm hàng năm trời thời gian phát triển. Việc viết design doc 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à các đội ngũ đối tác.

Tôi đã từng viết design doc với tư cách là lập trình viên tại Google, Microsoft và trong chính các công ty của riêng mình. Các chi tiết cụ thể có thể khác nhau, nhưng những nguyên tắc cốt lõi thì vẫn giữ nguyên. Một bản design doc làm rõ những vấn đề hóc búa mà bạn đang giải quyết và giúp các đồng nghiệp đưa ra phản hồi cho bạn.

Dưới đây, tôi chia sẻ phương pháp của mình để tạo ra các bản design doc hiệu quả, đồng thời giải thích những gì nên và không nên có trong một bản design doc.

Ví dụ về một bản design doc🔗

Câu hỏi phổ biến nhất mà tôi nhận được về design doc là làm sao để tìm được một bản mẫu chất lượng. Tôi chưa từng thấy một bản design doc công khai nào mà tôi cho là chất lượng cao cả. Tất cả các bản của tôi đều được lưu giữ nội bộ tại những công ty đã thuê tôi viết chúng.

Vì vậy, tôi đã tự viết một bản design doc từ đầu dựa trên những nguyên tắc mà tôi chia sẻ ở đây. Nó trình bày thiết kế cho một ứng dụng web thực tế mà tôi đang xây dựng.

Tôi đã tạo bản design doc này trước khi viết bất kỳ dòng code nào và tôi đang tuân thủ đúng thiết kế đó trong quá trình triển khai ứng dụng.

Bản thiết kế này chi tiết hơn mức tôi thường viết cho một dự án cá nhân, nhưng đây là độ dài và chiều sâu tương đương với một bản design doc mà tôi sẽ tạo nếu phải phối hợp công việc với người khác trong một dự án chuyên nghiệp.

Khi nào bạn nên viết design doc?🔗

Dự án càng phức tạp hoặc càng nhiều rủi ro thì việc viết design doc càng trở nên giá trị.

Hãy cân nhắc những câu hỏi sau:

Nếu bạn trả lời “có” cho bất kỳ câu hỏi nào trong số này, thì việc bỏ công sức viết một bản design doc là hoàn toàn xứng đáng. Nếu bạn trả lời “có” cho từ hai câu trở lên, thì gần như chắc chắn bản design doc đó sẽ mang lại hiệu quả tương xứng với công sức bạn bỏ ra.

Bạn nên đầu tư bao nhiêu công sức vào design doc?🔗

Một bản design doc có thể chỉ là một trang đơn giản hoặc một tài liệu dài 50 trang cần sự phê duyệt từ năm đội ngũ 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 một bản design doc, cũng giống như không có quy tắc nào quy định bạn nên kiểm thử code của mình bao nhiêu là đủ. 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, mức đầu tư phù hợp cho một bản design doc là bằng không.

Những gì nên có trong một bản design doc?🔗

Nếu bạn liệt kê mọi chi tiết nhỏ nhặt vào design doc, về cơ bản bạn đã thực hiện xong phần triển khai ngay trong giai đoạn thiết kế. Điều đó sẽ làm mất đi mục đích chính của một bản design doc.

Theo kinh nghiệm, bạn có thể tự hỏi một câu đơn giản để quyết định xem một quyết định có nên đưa vào design doc hay không: cái giá phải trả nếu làm sai là gì?

Cái giá phải trả nếu làm sai là gì?🔗

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 khi đã viết 200 nghìn dòng code rằng Ruby on Rails mới là lựa chọn tốt hơn, thì bạn đã rơi vào thế bí. Việc viết lại từ đầu là điều không khả thi, và ngay cả khi bạn xoay xở để viết code mới bằng Rails, bạn vẫn phải duy trì code bằng hai ngôn ngữ hoàn toàn khác biệt.

Những quyết định thiết kế khác lại rất tầm thường. Ví dụ, nếu ứng dụng của bạn hiển thị danh sách 100 bài viết, liệu tất cả có nên xuất hiện cùng lúc không? Hay người dùng nên xem 25 bài một lần và nhấp vào “Load more” để xem 25 bài tiếp theo?

Điều đó không quan trọng.

Nút “Load more” không phải là vấn đề ở cấp độ 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 nó trong vài giờ. Bạn không cần phải trình bày chi tiết toàn bộ quá trình suy nghĩ của mình trong design doc, và chắc chắn bạn không nên lãng phí thời gian họp hành để tranh cãi về điều đó.

Các thành phần của một bản design doc🔗

Dưới đây, tôi đã liệt kê các phần phổ biến nên có trong design doc của bạn. Thông thường, bạn không cần phải có đầy đủ mọi phần cho mọi tài liệu. Hãy chọn những phần phù hợp với bạn.

Tiêu đề (Title)🔗

Đ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 của bạn trong các cuộc trò chuyện, vì vậy hãy chọn một cái tên ngắn gọn, đặc trưng và gợi hình.

Ví dụ, nếu bạn đang thêm một lớp caching giữa máy chủ ứng dụng và máy chủ cơ sở dữ liệu, RecencyBank sẽ là một cái tên hay. Nó dễ đọc và mô tả đúng mục đích dự án của bạn. Một cái tên tồi sẽ là “Project Flying Silver Horse” vì nó dài dòng và vô nghĩa.

Siêu dữ liệu (Metadata)🔗

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

Siêu dữ liệu

Mục tiêu (Objective)🔗

Mục tiêu là lời giải thích một câu về mục đích dự án của bạn. 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.

Mục tiêu

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

Bối cảnh (Background)🔗

Phần bối cảnh giải thích ngữ cảnh và động lực cho dự án. Nó nên trả lời được các câu hỏi sau:

Bối cảnh