- Design docs là một trong những yếu tố cốt lõi của văn hóa kỹ thuật phần mềm tại Google, là các tài liệu tương đối không chính thức do tác giả chính của một hệ thống hoặc ứng dụng phần mềm viết trước khi bắt đầu dự án lập trình
- Tài liệu hóa chiến lược triển khai ở mức cao và các quyết định thiết kế chính, đặc biệt nhấn mạnh vào các đánh đổi đã được cân nhắc khi đưa ra những quyết định đó
- Công việc của kỹ sư phần mềm không phải là viết mã mà là giải quyết vấn đề, và văn bản phi cấu trúc như Design doc ở giai đoạn đầu của dự án có thể là công cụ giải quyết vấn đề ngắn gọn và dễ hiểu hơn cả mã nguồn
Vai trò của Design docs trong vòng đời phát triển phần mềm
- Ngoài mục đích tài liệu hóa thiết kế phần mềm ban đầu, chúng còn thực hiện các chức năng sau:
- Xác định sớm các vấn đề thiết kế khi việc thay đổi vẫn còn ít tốn kém
- Đạt được sự đồng thuận về thiết kế trong tổ chức
- Bảo đảm xem xét các mối quan tâm xuyên suốt (cross-cutting concern)
- Lan tỏa kiến thức của các kỹ sư cấp cao trong tổ chức
- Hình thành nền tảng cho trí nhớ tổ chức về các quyết định thiết kế
- Đóng vai trò là tạo tác tóm tắt trong danh mục kỹ năng của nhà thiết kế phần mềm
Cấu trúc của Design doc
- Vì Design doc là tài liệu không chính thức và không có hướng dẫn nội dung cứng nhắc, quy tắc là viết theo định dạng phù hợp nhất với từng dự án cụ thể
- Context and scope: Cung cấp tổng quan về bối cảnh hình thành hệ thống mới và những gì thực sự sẽ được xây dựng
- Goals and non-goals: Liệt kê mục tiêu của hệ thống và những gì không phải mục tiêu
- The actual design
- System-context-diagram: Sơ đồ cho thấy hệ thống như một phần của môi trường kỹ thuật lớn hơn
- APIs: Phác thảo các API mà hệ thống cung cấp
- Data storage: Thảo luận cách lưu trữ/quản lý dữ liệu
- Code and pseudo-code: Chỉ đưa vào khi cần mô tả thuật toán mới
- Degree of constraint: Mức độ ràng buộc của không gian lời giải là một trong những yếu tố chính ảnh hưởng đến hình thức của tài liệu thiết kế
- Alternatives considered: Liệt kê các thiết kế thay thế có thể đạt được kết quả tương tự một cách hợp lý, đồng thời giải thích các đánh đổi của từng phương án và lý do chọn thiết kế chính
- Cross-cutting concerns: Giải thích các mối quan tâm chung của tổ chức như bảo mật, quyền riêng tư, khả năng quan sát ảnh hưởng thế nào đến thiết kế
Khi nào nên viết Design doc
- Việc có viết Design doc hay không phụ thuộc vào việc các lợi ích như đồng thuận tổ chức về thiết kế, tài liệu hóa, review từ senior có lớn hơn phần công việc bổ sung do viết tài liệu tạo ra hay không
- Nếu bài toán thiết kế không mơ hồ do độ phức tạp của vấn đề hoặc của giải pháp, thì giá trị của việc viết tài liệu là không cao
- Một Design doc quá gần với sổ tay triển khai có thể là không cần thiết
- Với việc tạo prototype và lặp nhanh, chi phí phát sinh khi viết Design doc có thể không phù hợp
Vòng đời của Design doc
- Creation and rapid iteration: Viết tài liệu và lặp nhanh với đồng nghiệp để tạo ra phiên bản ổn định
- Review: Được chia sẻ với nhóm độc giả rộng hơn để review
- Implementation and iteration: Cập nhật tài liệu khi có thay đổi thiết kế trong quá trình triển khai
- Maintenance and learning: Đóng vai trò là điểm vào dễ tiếp cận nhất để hiểu hệ thống
Ý kiến của GN⁺
- Design doc là một cách tốt để đạt được sự rõ ràng và tạo đồng thuận khi giải quyết những vấn đề khó nhất của các dự án phần mềm phức tạp. Việc nghiên cứu trước giúp tránh những phần coding không cần thiết nên tiết kiệm chi phí, nhưng đồng thời cũng phát sinh chi phí do tốn thời gian viết và review
- Vì vậy cần lựa chọn một cách khôn ngoan việc có viết Design doc hay không tùy theo từng dự án. Nếu có sự không chắc chắn trong thiết kế phần mềm, việc tham gia sớm của kỹ sư cấp cao là hữu ích, cần sự đồng thuận trong tổ chức về thiết kế, nhóm thường bỏ sót các mối quan tâm chung như bảo mật, hoặc cần tài liệu high-level cho thiết kế của hệ thống legacy, thì nên cân nhắc viết Design doc
- Đây là một ví dụ cho thấy rõ tầm quan trọng của tài liệu hóa trong quá trình thiết kế phần mềm, đặc biệt có thể giúp thiết lập văn hóa thiết kế nhất quán trong các nhóm quy mô lớn. Tuy vậy, vì gánh nặng tài liệu hóa có thể khiến kỹ sư ngại thực hiện, nên việc xây dựng hướng dẫn với mức độ và phạm vi phù hợp theo từng bối cảnh là rất quan trọng
- Cá nhân tôi cho rằng Design doc rất hữu ích ở các khía cạnh: 1) cân nhắc đánh đổi theo độ phức tạp của thiết kế, 2) phát hiện sớm các vấn đề thiết kế trước khi triển khai, 3) cung cấp tổng quan hệ thống để thành viên mới học nhanh hơn. Tuy nhiên cần tránh để tài liệu trở nên quá hình thức hoặc xa rời việc triển khai thực tế
- Có thể cân nhắc bắt buộc Design doc chỉ ở giai đoạn đầu dự án hoặc ở các giai đoạn thiết kế có độ phức tạp cao, đồng thời đưa ra incentive để kỹ sư tự nguyện viết. Cũng nên nhấn mạnh rằng việc viết tài liệu còn giúp củng cố danh mục kỹ năng của từng kỹ sư
1 bình luận
Ý kiến trên Hacker News
Nhiều ý kiến khác nhau về văn hóa viết tài liệu thiết kế ở Google: