Văn hóa viết tài liệu Design Docs của Google (2020)
(industrialempathy.com)- Tại Google, Design Doc là tài liệu được viết trước khi code để sắp xếp bối cảnh vấn đề, chiến lược triển khai ở cấp độ cao và các quyết định thiết kế cốt lõi, qua đó giảm rủi ro khi chi phí thay đổi thiết kế còn thấp
- Giá trị của tài liệu này không nằm ở việc giải thích đoạn mã đã hoàn thành, mà ở chỗ làm rõ trade-off và các phương án thay thế để tổ chức cùng chia sẻ cơ sở cho một quyết định
- Một Design Doc tốt sẽ chứa các mối quan tâm xuyên suốt như bối cảnh và phạm vi, mục tiêu và phi mục tiêu, thiết kế thực tế, các phương án đã cân nhắc, bảo mật, quyền riêng tư, khả năng quan sát... theo cách phù hợp với từng dự án
- Nếu thiết kế đã quá rõ ràng hoặc tài liệu chỉ liệt kê quy trình triển khai, thì chi phí overhead của việc viết và review Design Doc có thể lớn hơn lợi ích nhận được
- Tài liệu này tiếp tục đi qua các giai đoạn viết, review, cập nhật trong lúc triển khai, rồi bảo trì và học hỏi; nếu thiết kế thay đổi trước khi phát hành thì nên cập nhật tài liệu cùng lúc
Vai trò của Design Doc
- Tại Google, Design Doc là một tài liệu tương đối phi chính thức do tác giả chính của một hệ thống phần mềm hoặc ứng dụng tạo ra trước khi bắt đầu dự án lập trình
- Tài liệu này chứa chiến lược triển khai ở cấp độ cao và các quyết định thiết kế cốt lõi, nhưng điều quan trọng không chỉ là danh sách quyết định mà còn là các trade-off cho thấy vì sao những lựa chọn đó được đưa ra
- Mục tiêu của software engineering không phải là sản xuất code, mà là giải quyết vấn đề; vì vậy ở giai đoạn đầu của dự án, văn bản phi cấu trúc đôi khi ngắn gọn và dễ hiểu hơn code
- Design Doc đảm nhận nhiều vai trò trong vòng đời phát triển
- Phát hiện sớm các vấn đề thiết kế khi chi phí thay đổi còn thấp
- Hình thành sự đồng thuận về thiết kế trong tổ chức
- Giúp không bỏ sót các mối quan tâm xuyên suốt như bảo mật, quyền riêng tư, khả năng quan sát
- Mở rộng tri thức của các kỹ sư senior ra toàn tổ chức
- Lưu lại ký ức tổ chức về các quyết định thiết kế
- Trở thành sản phẩm đầu ra tóm tắt portfolio kỹ thuật của người thiết kế
Cấu trúc cơ bản của Design Doc
- Design Doc không có mẫu cứng nhắc, và nguyên tắc đầu tiên là chọn định dạng phù hợp nhất với dự án cụ thể
- Tuy vậy, một cấu trúc thường hữu ích là bối cảnh và phạm vi, mục tiêu và phi mục tiêu, thiết kế thực tế, các phương án đã cân nhắc, các mối quan tâm xuyên suốt, và độ dài phù hợp
-
Bối cảnh và phạm vi
- Cung cấp tổng quan thô về môi trường nơi hệ thống mới sẽ tồn tại và chính xác những gì sẽ được xây dựng
- Vì đây không phải tài liệu yêu cầu nên cần ngắn gọn, tập trung vào việc giúp người đọc nhanh chóng nắm được bối cảnh
- Có thể giả định một phần kiến thức nền, và nối tới chi tiết qua liên kết
- Phần này nên tập trung vào các dữ kiện nền khách quan
-
Mục tiêu và phi mục tiêu
- Tóm tắt ngắn gọn các mục tiêu của hệ thống và đôi khi quan trọng hơn là các phi mục tiêu bằng danh sách bullet ngắn
- Phi mục tiêu không phải là phủ định đơn giản của mục tiêu như “hệ thống không được crash”, mà là những điều đáng lẽ có thể là mục tiêu nhưng đã được loại trừ rõ ràng
- Trong thiết kế cơ sở dữ liệu, việc tuân thủ ACID là ví dụ điển hình về thuộc tính cần biết là mục tiêu hay phi mục tiêu
- Dù là phi mục tiêu, nếu không có trade-off cản trở việc đạt mục tiêu thì vẫn có thể chọn giải pháp cung cấp thuộc tính đó
Cách viết phần thiết kế thực tế
- Phần thiết kế thực tế nên bắt đầu từ tổng quan rồi đi xuống chi tiết
- Design Doc là nơi ghi lại các trade-off phát sinh trong thiết kế phần mềm
- Dựa trên các dữ kiện của bối cảnh và các yêu cầu là mục tiêu cùng phi mục tiêu, tài liệu cần đề xuất giải pháp và cho thấy vì sao một giải pháp cụ thể đáp ứng mục tiêu tốt nhất
- Ưu điểm của định dạng tài liệu là có thể linh hoạt chọn cách biểu đạt phù hợp với tập vấn đề
-
Sơ đồ ngữ cảnh hệ thống
- Trong nhiều tài liệu, system-context-diagram có thể rất hữu ích
- Sơ đồ này cho thấy hệ thống như một phần của môi trường kỹ thuật lớn hơn, giúp người đọc hiểu thiết kế mới trong bối cảnh mà họ đã quen thuộc
-
API và lưu trữ dữ liệu
- Nếu hệ thống được thiết kế để expose API thì nhìn chung nên phác thảo API
- Nên tránh cách sao chép và dán nguyên xi các giao diện chính thức hoặc định nghĩa dữ liệu
- Những định nghĩa như vậy dễ trở nên dài dòng, chứa chi tiết không cần thiết và nhanh chóng lỗi thời
- Cần tập trung vào những phần liên quan đến thiết kế và trade-off
- Với hệ thống lưu trữ dữ liệu, tài liệu nên đề cập dữ liệu được lưu như thế nào và ở dạng đại khái ra sao
- Thay vì dán toàn bộ định nghĩa schema, tốt hơn là giải thích những phần liên quan đến các quyết định thiết kế
-
Code và pseudocode
- Nói chung không nên đưa nhiều code vào Design Doc
- Trừ trường hợp giải thích một thuật toán mới, pseudocode cũng chỉ nên dùng hiếm hoi
- Nếu có prototype cho thấy thiết kế là khả thi để triển khai thì có thể dẫn liên kết phù hợp
Mức độ ràng buộc làm thay đổi hình thức tài liệu
- Một trong những yếu tố chính ảnh hưởng đến hình thức của thiết kế phần mềm và Design Doc là mức độ ràng buộc của không gian lời giải
- Ở một cực là các dự án phần mềm greenfield chỉ có mục tiêu, còn giải pháp thì hầu như cái gì cũng có thể
- Loại tài liệu này có thể bao quát phạm vi rộng, nhưng cần nhanh chóng xác định các quy tắc để thu hẹp xuống một tập lời giải có thể quản lý được
- Ở cực còn lại là các hệ thống có các lời giải khả dĩ đã được xác định rõ, nhưng chưa rõ phải kết hợp chúng thế nào để đạt mục tiêu
- Có thể đó là hệ thống legacy khó thay đổi
- Hoặc là thiết kế thư viện phải hoạt động trong các ràng buộc của ngôn ngữ lập trình host
- Trong những trường hợp như vậy, có thể liệt kê các việc tương đối dễ làm, nhưng cần kết hợp chúng một cách sáng tạo để đạt mục tiêu
- Nếu có nhiều giải pháp mà không giải pháp nào hoàn hảo, tài liệu nên tập trung chọn ra cách tốt nhất dựa trên các trade-off đã xác định
Các phương án thay thế và mối quan tâm xuyên suốt
-
Các phương án đã cân nhắc
- Phần này 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ý
- Cần tập trung vào các trade-off mà mỗi thiết kế tạo ra, và cách những trade-off đó dẫn tới lựa chọn cuối cùng
- Những giải pháp không được chọn có thể được trình bày ngắn gọn, nhưng phần này rất quan trọng trong tài liệu
- Cần cho người đọc thấy vì sao các giải pháp khác mà họ có thể thắc mắc lại kém hấp dẫn hơn khi đối chiếu với mục tiêu dự án
-
Các mối quan tâm xuyên suốt
- Tổ chức có thể dùng phần này để bảo đảm các mối quan tâm xuyên suốt như bảo mật, quyền riêng tư, khả năng quan sát luôn được cân nhắc
- Thông thường đây là các mục ngắn giải thích mỗi mối quan tâm ảnh hưởng thế nào đến thiết kế và được xử lý ra sao
- Mỗi team cần quyết định những mối quan tâm nào sẽ trở thành tiêu chuẩn trong bối cảnh của mình
- Các dự án tại Google yêu cầu một Privacy Design Doc riêng vì mức độ quan trọng của quyền riêng tư, và có review chuyên biệt cho cả quyền riêng tư lẫn bảo mật
- Việc hoàn tất review là yêu cầu cho tới thời điểm dự án phát hành
- Best practice là phối hợp với các team quyền riêng tư và bảo mật càng sớm càng tốt để thiết kế phản ánh các yêu cầu này ngay từ đầu
- Nếu đã có tài liệu chuyên biệt cho chủ đề đó, Design Doc trung tâm có thể chỉ tham chiếu thay vì lặp lại chi tiết
Độ dài và khi nào không cần viết
-
Độ dài phù hợp
- Design Doc cần đủ chi tiết nhưng cũng phải đủ ngắn để những người bận rộn thật sự có thể đọc hết
- Với dự án lớn, khoảng 10–20 trang có vẻ là điểm phù hợp
- Nếu dài hơn nhiều, có thể nên chia vấn đề thành các bài toán con dễ quản lý hơn
- Cũng có thể có mini Design Doc dài 1–3 trang
- Loại này đặc biệt hữu ích cho các cải tiến dần dần hoặc các đầu việc con trong dự án agile
- Nó vẫn đi qua các bước như tài liệu dài, nhưng ngắn gọn hơn và tập trung vào tập vấn đề hẹp hơn
-
Khi không cần viết
- Việc viết Design Doc có overhead
- Có nên viết hay không phụ thuộc vào việc lợi ích như đồng thuận thiết kế, tài liệu hóa và review từ kỹ sư senior có vượt qua chi phí tạo tài liệu hay không
- Tiêu chí phán đoán cốt lõi là vấn đề thiết kế có mơ hồ hay không
- Sự mơ hồ có thể đến từ độ phức tạp của vấn đề, độ phức tạp của giải pháp, hoặc cả hai
- Nếu không mơ hồ thì giá trị của quá trình viết tài liệu là thấp
- Nếu tài liệu trên thực tế chỉ là sổ tay triển khai, có thể không cần Design Doc
- Nếu tài liệu chỉ nói “sẽ triển khai như thế này” mà không có trade-off, phương án thay thế hay giải thích quyết định, thì có lẽ tốt hơn là bắt tay vào viết chương trình luôn
- Nếu giải pháp quá rõ ràng đến mức không có trade-off thì giá trị của tài liệu thấp
- Overhead của việc viết và review Design Doc có thể không phù hợp với prototyping và lặp nhanh
- Việc theo phương pháp agile không có nghĩa là có thể bỏ qua chuyện suy nghĩ nghiêm túc về lời giải cho một vấn đề đã biết
- Bản thân prototyping cũng có thể là một phần của quá trình viết Design Doc, và việc “đã thử và nó chạy được” có thể là bằng chứng rất mạnh cho một lựa chọn thiết kế
Vòng đời của Design Doc
- Vòng đời của Design Doc gồm bốn giai đoạn
- Viết và lặp nhanh
- Review
- Triển khai và lặp tiếp
- Bảo trì và học hỏi
-
Viết và lặp nhanh
- Tài liệu có thể do tác giả viết một mình hoặc đồng viết cùng các cộng tác viên
- Sau đó nó được chia sẻ với những đồng nghiệp hiểu rõ nhất không gian vấn đề để lặp nhanh
- Các câu hỏi làm rõ và đề xuất từ đồng nghiệp giúp tài liệu đi tới một phiên bản đầu tương đối ổn định
- Ở Google, cũng có những kỹ sư và team thích tạo tài liệu bằng hệ thống quản lý phiên bản và công cụ review code, nhưng phần lớn Design Doc được viết trên Google Docs và tận dụng nhiều tính năng cộng tác
-
Review
- Ở giai đoạn review, tài liệu được chia sẻ cho nhóm độc giả rộng hơn so với tác giả ban đầu và các cộng tác viên gần gũi
- Review có thể mang lại giá trị lớn nhưng cũng dễ trở thành cái bẫy overhead, nên cần xử lý cẩn thận
- Cách nhẹ nhàng là gửi tài liệu tới mailing list của team rộng hơn để mọi người có cơ hội xem qua
- Thảo luận chủ yếu diễn ra trong các thread bình luận của tài liệu
- Cách nặng hơn là cuộc họp review thiết kế chính thức, nơi tác giả trình bày tài liệu trước các kỹ sư senior
- Nhiều team ở Google có các cuộc họp định kỳ cho kiểu review này
- Nếu phải chờ những cuộc họp đó, quy trình phát triển có thể chậm đi đáng kể
- Có thể giảm tác động bằng cách chủ động xin phản hồi quan trọng nhất trực tiếp và không biến review diện rộng thành yếu tố chặn tiến độ
- Khi Google còn là công ty nhỏ hơn, thông lệ là gửi thiết kế lên một mailing list trung tâm và để các kỹ sư senior review khi họ có thời gian
- Cách làm này có ưu điểm là tạo ra một văn hóa thiết kế phần mềm tương đối đồng đều trên toàn công ty
- Khi tổ chức kỹ thuật phát triển lớn hơn nhiều, việc duy trì cách tiếp cận tập trung trở nên khó khăn
- Giá trị chính của review là tạo cơ hội để kinh nghiệm kết hợp của tổ chức được phản ánh vào thiết kế
- Đặc biệt, giai đoạn review liên tục giúp bảo đảm thiết kế có cân nhắc các mối quan tâm xuyên suốt như khả năng quan sát, bảo mật và quyền riêng tư
- Giá trị cốt lõi của review không chỉ là phát hiện vấn đề, mà là phát hiện chúng sớm trong vòng đời phát triển khi chi phí thay đổi còn thấp
-
Triển khai và lặp tiếp
- Khi đã có đủ tự tin rằng các review bổ sung khó có khả năng buộc phải thay đổi lớn thiết kế, đó là lúc bắt đầu triển khai
- Khi kế hoạch va chạm với thực tế, sẽ xuất hiện lỗi, các yêu cầu chưa được xử lý, hoặc những giả định hóa ra sai, và khi đó có thể cần thay đổi thiết kế
- Trong trường hợp này, việc cập nhật Design Doc được khuyến nghị mạnh mẽ
- Theo kinh nghiệm thực tế, nếu hệ thống được thiết kế vẫn chưa phát hành thì nhất định phải cập nhật tài liệu
- Trên thực tế, mọi người thường không cập nhật tài liệu tốt, và vì nhiều lý do công việc khác, các thay đổi thường bị tách ra thành tài liệu mới
- Kết quả là thay vì một tài liệu nhất quán, nó có thể trở thành trạng thái giống như Hiến pháp Hoa Kỳ kèm hàng loạt tu chính án
- Nếu đặt liên kết từ tài liệu gốc tới các tài liệu sửa đổi như vậy, điều đó sẽ rất hữu ích cho các lập trình viên bảo trì sau này khi họ phải làm khảo cổ Design Doc để hiểu hệ thống mục tiêu
-
Bảo trì và học hỏi
- Khi một kỹ sư Google gặp một hệ thống mà họ lần đầu chạm vào, câu hỏi đầu tiên thường là: “Design Doc ở đâu?”
- Giống như mọi tài liệu khác, Design Doc theo thời gian cũng có xu hướng lệch khỏi thực tế, nhưng nó thường là điểm vào dễ tiếp cận nhất để học quá trình tư duy đã tạo ra hệ thống
- Người viết nên đọc lại Design Doc của chính mình sau 1–2 năm
- Xem mình đã đúng điều gì
- Xem mình đã sai điều gì
- Nghĩ xem nếu là hôm nay thì mình sẽ quyết định khác đi ở đâu
- Quá trình trả lời những câu hỏi đó giúp kỹ sư trưởng thành hơn và cải thiện năng lực thiết kế phần mềm theo thời gian
Cách phán đoán khi nào nên bắt đầu bằng Design Doc
- Design Doc là cách tốt để đạt được sự rõ ràng và xây dựng đồng thuận khi giải các bài toán khó trong dự án phần mềm
- Nó có thể tiết kiệm chi phí bằng cách giảm những ngõ cụt trong quá trình code mà lẽ ra có thể tránh được nếu nghiên cứu trước
- Đồng thời, nó cũng tạo ra chi phí vì cần thời gian để viết và review
- Có thể cân nhắc các câu hỏi sau
- Thiết kế phần mềm đúng đắn có còn bất định đến mức hợp lý để dành thời gian suy nghĩ trước nhằm tăng độ chắc chắn hay không?
- Có hữu ích không nếu lôi kéo các kỹ sư senior vào giai đoạn thiết kế, những người có thể không review được mọi thay đổi code?
- Thiết kế phần mềm có mơ hồ hoặc gây tranh cãi tới mức sự đồng thuận ở cấp tổ chức là có giá trị không?
- Team có thỉnh thoảng quên các yếu tố như quyền riêng tư, bảo mật, logging hoặc các mối quan tâm xuyên suốt khác trong thiết kế không?
- Tổ chức có thực sự cần một tài liệu cung cấp góc nhìn cấp cao về thiết kế của các hệ thống legacy bên trong không?
- Nếu trả lời “có” cho 3 câu trở lên, thì rất có thể Design Doc là cách tốt để bắt đầu dự án phần mềm tiếp theo của bạn
1 bình luận
Ý kiến trên Hacker News
Tôi đã rời Google vì văn hóa tài liệu thiết kế của họ
Ngay sau khi vào công ty, tôi viết một tài liệu ở mức độ rất cao cho một công việc tương đối nhỏ mà tôi đã làm nhiều lần ở các mảng sản phẩm khác, rồi một đồng nghiệp kéo tôi ra nói riêng rằng “ở đây chúng tôi không làm như vậy”
Cách tôi đề xuất chỉ là một biến thể nhỏ của cách làm được khuyến nghị, nhưng họ bảo tôi “hãy đánh giá thêm nhiều cách khác để hoàn thành việc này”, và khi tôi hỏi lý do thì họ trả lời “để cho thấy là bạn đã cân nhắc đủ rộng”
Ở Google rõ ràng có công việc giả tạo, và tôi ước gì mình đã vào một đội khác
Văn hóa Google đã trở thành một kiểu sùng bái hàng hóa đang bắt chước chính nó
Một vài công ty tôi làm sau Google lại ngại thảo luận chi tiết về quy trình thăng tiến, vì họ đã thấy chuyện gì xảy ra khi mọi người tối ưu vi mô để khớp với quy trình đó
Ai cũng bận nên không thể nói chuyện 1:1 nhẹ nhàng với tất cả mọi người, và nếu không nhận được phản hồi từ các bên liên quan một cách đúng đắn thì rất dễ có những người tức giận tìm tới và khiến bản phát hành phải rollback
Trong bối cảnh đó, tài liệu thiết kế là một công cụ giao tiếp bất đồng bộ cho những chủ đề có lượng thông tin lớn. Nếu sản phẩm thành công, thì 10 năm sau bạn vẫn sẽ “trò chuyện” với những người mới gia nhập thông qua tài liệu này
Tôi đã nhiều lần được cứu nhờ một tài liệu thiết kế ngẫu nhiên từ năm 2010 giải thích các quyết định kỳ quặc vẫn còn cản trở chúng tôi đến bây giờ. Nó có thể không hợp với những đội nhỏ linh hoạt hay các công việc ít phức tạp hơn, nhưng ngay cả khi đã thành kiểu sùng bái hàng hóa trong văn hóa kỹ thuật, nhìn chung nó vẫn có lý do và bối cảnh riêng
Nếu bạn đang thiết kế một thứ gì đó mà chỉ có đúng một giải pháp được cân nhắc, thì hoặc là không có thiết kế, hoặc là việc thiết kế chưa đủ kỹ. Các lựa chọn và đánh đổi là những gì tạo nên thiết kế
Nhiều người trong số đó là tư vấn viên bên ngoài đã làm việc với công ty hơn 15 năm, nên đúng là cũng đã có một mức độ tiêu chuẩn nào đó nhờ cùng những con người ấy làm đi làm lại cùng loại việc. Nhưng dù vậy, họ vẫn cố dựng lên một hình nộm kiểu “nếu mọi người không theo tiêu chuẩn thì sao”
Kết quả là tài liệu thiết kế либо không có, либо đã lỗi thời nghiêm trọng, và công ty năm nào cũng phải tiếp tục thuê lại chính những tư vấn viên đó với chi phí bị thổi phồng
Còn bây giờ tôi ở một đội có nhiều Googler kỳ cựu với thâm niên trên 15 năm, và tài liệu thiết kế chỉ tồn tại khi thực sự cần thiết. Chẳng hạn khi liên quan đến nhiều hệ thống, hoặc có quá nhiều đánh đổi nên rõ ràng là phức tạp. Ngoài ra thì thường chỉ là kiểu “hãy viết CLS”
Ở Google, có vẻ tài liệu thiết kế là tư liệu cốt lõi được đưa vào hồ sơ thăng chức, nên mới sinh ra vấn đề như vậy
Vì thế tài liệu thường được viết với sự để tâm tới hội đồng thăng chức nhiều hơn là những người thực sự làm việc với hệ thống đó, tức độc giả vốn có của tài liệu
Mỗi lần vào công ty mới, tôi đều đề xuất bắt đầu viết tài liệu thiết kế, và như thế lập tức tạo ấn tượng tốt với ban quản lý :)
Nhiều tài liệu tôi từng đọc trông như đã chốt sẵn quyết định mong muốn từ trước, rồi đến lúc bắt đầu tài liệu mới gắn thêm hai hoặc nhiều phương án được bày ra chỉ để làm nổi bật quyết định đó. Một phương án thì quá đơn giản, một phương án thì over-engineering không cần thiết, rồi chọn phương án trông có vẻ hợp lý
Vì không biết tài liệu thiết kế nào sẽ được dùng trong hồ sơ thăng chức, nên dù việc nhỏ đến đâu cũng để lại thành tài liệu thiết kế. Có khái niệm tài liệu thiết kế 1 trang, nhưng thường nó sẽ phình từ một trang thành nhiều trang
Cả dự án kéo dài 1 tuần cũng có tài liệu thiết kế, và cũng có lúc tôi phải review các tài liệu thiết kế dài 20, 30, 40 trang cho những việc mà ở công ty khác chỉ cần một ticket JIRA là xong
Nhiều người được dạy rằng hội đồng thăng chức muốn thấy “tài liệu do một mình tác giả viết”, và dù điều đó có đúng hay không thì niềm tin này cũng khiến mọi thứ chậm hơn và kìm hãm việc học hỏi chéo. Tôi từng thấy cả kỹ sư phần mềm bị cô lập hơn một quý chỉ để viết tài liệu thiết kế
Trong tài liệu thiết kế, lẽ ra bản thân thiết kế phải là trọng tâm, nhưng 99% còn lại lại là phần định nghĩa vấn đề. Có quá nhiều lần trong lúc review, khi cải thiện phần định nghĩa vấn đề thì phải bỏ luôn thiết kế và viết lại phần lớn tài liệu
Tệ nhất là khi vừa cải thiện phần định nghĩa vấn đề thì lộ ra một cách giải quyết đơn giản, không cần đến thiết kế phức tạp. Người viết đã đầu tư rất nhiều thời gian vào thiết kế phức tạp đó, và về mặt lịch sử cũng có nhiều hội đồng coi sự phức tạp ấy là căn cứ thăng chức, nên họ chống lại lời giải đơn giản
Tôi cũng từng thấy những tài liệu thiết kế hoàn toàn không có phương án thay thế nào. Chúng chỉ là bản mô tả dài dòng, tốn công ghi chép về việc cần làm hoặc điều ai đó muốn làm
Cứ thế, nếu nhìn mờ đi thì tài liệu thiết kế dần giống một hệ thống theo dõi bug. Ai cũng bận với tài liệu thiết kế của mình, còn bug thì không ai xử lý. Vì sửa bug thì không thăng chức được
Người ta hay nói rằng vào team mới thì chỉ cần xem tài liệu thiết kế là được, nhưng thực tế thường không có nơi trung tâm để theo dõi chúng. Ở nhiều team, tài liệu thiết kế không thuộc sở hữu của team hay dự án mà thuộc sở hữu cá nhân, vì như vậy có thể đảm bảo không ai khác đóng góp vào đó, và chuyện này cũng lại vì hội đồng thăng chức
Cũng có rất nhiều tài liệu thiết kế mà bạn không có quyền truy cập, không phải vì quá mật mà chỉ đơn giản là nó đang như vậy. Không phải team chỉ có hai ba tài liệu thiết kế, mà là có cả một núi tài liệu cần đọc. Trong bối cảnh chu kỳ chuyển nhóm ở Google khoảng 2 năm, rất nhiều tài liệu cứ thế biến mất theo thời gian
Ở công ty khác, điều này chẳng khác nào bảo người mới vào team rằng “mọi thứ cần biết chỉ cần đọc toàn bộ bug đã đóng hoặc tất cả commit message trên nhánh chính là được”
Ở nơi khác, có lẽ sau bữa trưa tôi đã bị giữ lại trước bảng trắng cùng cả team vài tiếng để định nghĩa vấn đề. Các senior sẽ dạy junior theo thời gian thực cách suy nghĩ về những vấn đề như thế này, rồi lặp nhanh nhiều vòng
Phần lớn nội dung như vậy thường sẽ được viết trong hệ thống theo dõi bug, hoặc nếu là việc lớn thì ghi vào wiki dự án hay thư mục chung để nó trở thành tài sản của mọi người
Tất cả những vấn đề trên đều có thể cải thiện, và thực tế người ta cũng đã thử cải thiện, nhưng văn hóa thay đổi rất chậm. Bản thân khái niệm tài liệu thiết kế là tốt, nhưng có cạm bẫy, và cách nhiều người ở Google đang dùng nó không phải là câu trả lời
Tôi nhớ những tài liệu thiết kế có giá trị lớn hơn chi phí bỏ ra
Nhìn chung tôi chưa thấy chiến lược đó thực sự hiệu quả
Ngược lại, từng có những tài liệu dài dùng để cung cấp bối cảnh, sắp xếp lại team đã làm gì, đang làm gì và vấn đề là gì, và những tài liệu kiểu đó thường có xu hướng dài dòng và bị thổi phồng
Tôi làm ở công ty được nhắc đến, nhưng không có trải nghiệm giống tác giả.
Có nhiều kiểu tài liệu thiết kế, và trong số đó tôi không thấy cái nào hữu ích. Rất hiếm khi tôi thấy một tài liệu thiết kế hữu ích ở Google. Tài liệu thiết kế tạo cảm giác như dành cho các kỹ sư quá thiên về quy trình.
Những kiểu tôi từng thấy đại khái như sau: tài liệu thiết kế để thăng chức không giải thích nó định giải quyết điều gì, mà chỉ nói dự án này tuyệt vời đến đâu và sẽ khiến công ty tốt hơn thế nào. Kết luận logic là tác giả nên được thăng chức.
Tài liệu thiết kế turbo encabulator là thứ văn bản tán gẫu kỹ thuật đầy những thuật ngữ chưa từng thấy, đến mức nếu không phải senior của nhóm thì không thể hiểu nổi. Đôi khi tôi cũng không chắc các senior có hiểu hay không.
Tài liệu thiết kế của sinh viên mới ra trường thì không có nội dung gì, nhưng được kéo dài tối đa để chứng minh một người vừa tốt nghiệp đại học muốn chứng tỏ điều gì đó. Nó không truyền đạt thông tin, mà thường nhồi khoảng 70 trang bằng cách copy-paste thật to phần mã đã viết sẵn.
Tài liệu thiết kế với sự thật bịa đặt thì đầy những câu kiểu “ai cũng biết”, “mọi người đều nói vậy”. Không trắng trợn như chính trị gia, nhưng vẫn cố ép phương án thiết kế của mình bằng các câu như “cái này tuân theo thực tiễn tốt”, “phần mềm này chậm, vì vậy…”. Thiếu mất ai định nghĩa thế nào là thực tiễn tốt, vì sao nó tốt, cái gì đang chậm, đã đo chưa, hay chỉ là cảm nhận của người dùng cuối.
99% tài liệu thiết kế tôi từng thấy đều như vậy. Có ngoại lệ, nhưng theo kinh nghiệm của tôi thì rất hiếm. Tôi ngạc nhiên khi tác giả lại thúc đẩy cách làm này. Dù vậy, ông ấy là giám đốc chứ không phải kỹ sư, nên ở vị trí đó tài liệu thiết kế có thể hợp lý, nhưng tôi vẫn không rõ những người như vậy thực sự mang lại giá trị gì.
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
Điều nổi bật tôi nhận ra sớm là các tài liệu thiết kế được lưu trong Google Docs có xu hướng chất lượng thấp hơn các tài liệu nằm trong kho lưu trữ có quản lý phiên bản. Tôi không biết đó có phải là chỉ dấu gián tiếp về thời điểm viết hay là do quy trình code review nghiêm ngặt hơn việc chỉnh sửa Docs.
Khi tôi viết các tài liệu thiết kế lớn, có lẽ khoảng 40 trang, tôi làm theo thông lệ là viết bằng HTML thủ công và đưa qua hệ thống code review. Tôi cũng đăng lên mailing list trung tâm và web server, và việc nhận phản hồi từ employee #3 cũng rất hay. Chúng được sắp theo danh mục ở một nơi trung tâm nên rất dễ tìm.
Tôi không nhớ rằng chỉ riêng một tài liệu thiết kế từng chiếm trọng số lớn đến mức quan trọng cho việc thăng chức. Việc thăng chức đáng ra phải dựa trên tổng thể ảnh hưởng, chứ không phải một sản phẩm đầu ra cụ thể. Tất nhiên hệ thống có những khiếm khuyết lớn, và các quyết định gây ngạc nhiên theo nghĩa xấu cũng thường xuất hiện, nhưng khi đó tôi không nhớ đã từng đọc những tài liệu thiết kế được tối ưu cho đánh giá thành tích.
Nếu bạn tìm được trang web tập hợp các tài liệu thiết kế HTML viết tay thời kỳ đầu, tôi khuyên nên xem lướt qua. Có thể khi hệ thống lúc đó còn đang vận hành, chúng sẽ còn hữu ích hơn nữa.
Một số tài liệu cũ như SmartASS đầy những giải thích chi tiết về các phương trình và mô hình nền tảng, rất hữu ích để hiểu cách nó hoạt động và vì sao họ chọn cách tiếp cận đó. Sau này chúng cũng ảnh hưởng đến công việc thiết kế của tôi. Tôi không phải giám đốc mà chỉ là kỹ sư bình thường, và chúng thực sự có ích.
Trong số các tài liệu thiết kế của Chrome được liên kết từ trang chromium.org cũng có những tài liệu trước đây từng giúp tôi hiểu cấu trúc.
Nó buộc các lập trình viên junior phải nghĩ trước về lời giải và biện minh cho quyết định của mình, đồng thời cho phép các lập trình viên senior kiểm chứng quyết định đó và đưa ra phản hồi bất đồng bộ.
Tuy vậy, tôi luôn làm ở startup nên chưa từng làm trong tổ chức kỹ sư hơn 30–40 người. Big Tech có thể khác, nhưng trải nghiệm của tôi là tích cực.
Tương tự, nếu việc giải thích cho kỹ sư khác mất khá nhiều thời gian, dù chỉ khoảng 30 phút thôi, thì bạn nên viết tài liệu để tiết kiệm thời gian.
Tôi không hiểu sao có thể nghĩ rằng hoàn toàn không cần viết tài liệu.
Sau này khi chuẩn bị cho việc thăng chức, người ta sẽ thêm đủ ngữ cảnh vào các tài liệu thuộc nhóm số 2 để biến chúng thành nhóm số 1.
Việc tài liệu hóa nhìn chung là tốt, nhưng cách tiếp cận này có vẻ có vấn đề.
Ở đây nói rằng “trước khi bắt tay vào dự án code”, tác giả chính của một hệ thống phần mềm hay ứng dụng sẽ tạo một tài liệu tương đối không chính thức, nhưng bản thân việc thiết kế chính là một dự án code, và hai việc đó là một.
Ý tưởng rằng bạn có thể giải quyết xong thiết kế trên giấy trước khi commit code là sai. Cách tiếp cận bằng tài liệu thiết kế thực ra cũng thừa nhận rằng lúc đầu vẫn phải viết một ít code, nhưng lại cố tách nó ra thật chặt thành “prototype để chứng minh tính khả thi của thiết kế”.
Đặc điểm lớn của tài liệu thiết kế viết trước là nó cho phép mọi người soi mói, tức là review, trước khi phần code nghiêm túc bắt đầu. Theo kinh nghiệm của tôi, như vậy tài liệu sẽ ngày càng phình ra với nhiều gợi ý hơn và những cuộc bàn luận phương án thay thế vô nghĩa, đến mức nó không còn là tài liệu thiết kế mà trở thành tài liệu kiểu “làm ơn cho tôi được xây cái này đi”.
Nếu có một vấn đề kiến trúc quan trọng cần đổi hướng, thì tốt hơn là nói chuyện và cộng tác trước với đúng những người phù hợp, thay vì làm một tài liệu thiết kế chi tiết rồi bị bắn hạ.
Nếu giữ nó gần hơn với ý niệm “tài liệu tương đối không chính thức” và cập nhật tài liệu trong lúc thực hiện, thì nó thực sự có thể hữu ích. Vì như vậy bạn có thể vừa xây một hệ thống chạy được vừa tạo ra tài liệu hữu ích. Nhưng như thế nó gần với tài liệu hóa như một phần của quá trình liên tục và cộng tác hơn là một tài liệu thiết kế.
Tôi là Googler. Cũng đã công bố vài bài báo, nhưng trước đây từng ghét viết tài liệu thiết kế. Từ vài năm trước tôi nhận ra những lợi ích chính mà nó mang lại cho mình
Nó giúp tôi gạt phần tức thời của ý tưởng ra khỏi đầu để chuyển sang những phần sâu hơn và các cân nhắc hữu ích hơn
Các khiếm khuyết hiện ra rõ hơn, đặc biệt là với chính tôi
Việc chia sẻ suy nghĩ trở nên dễ hơn, nhất là với những người ở văn phòng khác. Họ thường đưa ra phản hồi rất tốt
Nó giúp tôi nắm được khối lượng công việc cần thiết tốt hơn nhiều so với khi cứ thế bắt đầu code
Nó thường làm lộ ra những điều cần học trước khi code, như các hệ thống lân cận hay lựa chọn công nghệ phù hợp
Nó cũng tốt cho thăng chức, nhưng một dự án thành công còn tốt hơn. Tôi thường được nói rằng tài liệu của tôi hữu ích, nên có vẻ tôi đã tìm ra hướng đi đúng
Nó có thực sự hiệu quả không? Có tốt hơn các phương án khác không? Thảo luận đó ở đâu?
Khi làm ở Amazon, văn hóa tài liệu thiết kế rất tuyệt. Công việc tiếp theo có vẻ vay mượn văn hóa kỹ thuật của Google hoặc văn hóa startup phổ biến ở SF, nhưng quy trình tài liệu thiết kế ở đó giống như một trò đùa vô dụng
Nó là một cơ chế gắn với văn hóa làm việc rộng hơn. Nếu làm việc một mình thì đó là một bài tập hơi xa xỉ, còn với một đội ngũ khổng lồ thì nó giúp tận dụng nhiều chuyên môn hơn của cả nhóm và cũng đóng vai trò như tài liệu hóa
Có một số kiểu thất bại. Việc coi trọng đầu ra tài liệu hơn kết quả là một kiểu lệch pha điển hình. Kiểu như viết tài liệu 40 trang để thăng chức, điều này thường không hiệu quả trừ khi bạn ở mức rất junior và đang cố chứng minh rằng mình có thể nối các câu với nhau hơn là làm kỹ thuật chuyên sâu
Nó cũng là quá mức với các nhóm làm việc đơn lẻ. Một số nhóm nhỏ khác có thể giao tiếp đủ tốt chỉ bằng issue, chẳng hạn Jira, và các buổi riêng để đối chiếu ý tưởng
Kỹ sư cũng cần được onboarding về cách viết tài liệu thiết kế hiệu quả. Bình luận đứng đầu nản lòng vì lần thử đầu tiên không được tán thưởng ngay có thể là một tín hiệu
Viết về code là khó, và trên HN kiểu luyện tập này thường được khen ngợi. Nếu làm việc trong nhóm, hãy cẩn thận khi bạn bắt đầu cảm thấy công việc của mình chỉ gồm những thứ luôn có thể giải thích bằng tài liệu dễ chia sẻ và không cần suy nghĩ sâu
Nếu một nhà đầu tư lớn giấu danh tính và làm kỹ sư Google trong vài tuần, họ sẽ lập tức trở thành một nhà đầu tư chủ động đòi sa thải Sundar
Quy mô tiềm năng con người bị lãng phí vì văn hóa tài liệu thiết kế ở Google gần như khó mà hình dung nổi
Phần lớn hoạt động phát triển cứ thế diễn ra, thỉnh thoảng mới vội viết tài liệu để dễ biện minh cho CL hơn
Chỉ khoảng 1 trên 10 trường hợp tôi thấy ai đó làm quá tay, nhưng với một kỹ sư phần mềm trung bình thì đây không phải lãng phí thời gian lớn
Nếu muốn đốt càng nhiều tiền càng tốt, có lẽ bạn sẽ thiết kế công ty đúng như vậy
Văn hóa tài liệu thiết kế có xu hướng đẩy mọi người vào một tầng lớp phải tự biện minh cho công việc của mình. Văn hóa biện minh là một khuôn mẫu khá đè nén với những người đổi mới, ngay cả khi đồng nghiệp cũng củng cố nó như một phần văn hóa
Hệ thống này có xu hướng ngăn cản các nỗ lực có tầm nhìn và các dự án đầy tham vọng. Những nỗ lực không dựa trên đồng thuận bị bóp nghẹt, và nếu nghĩ ra điều gì “ngoài chuẩn mực được cho phép” thì bạn sẽ bị tập thể trừng phạt
Những hệ thống như vậy sinh ra tư duy bầy đàn, và tính chất đặt nặng truyền thống của “cách chúng tôi làm việc” về bản chất buộc người ta vào tình huống làm việc theo cách khác sẽ trở thành rủi ro nghề nghiệp
Ở Silicon Valley có đủ kiểu văn hóa công ty dựa vào những sáo ngữ được gói bằng thuật ngữ ‘agile’ và ‘design thinking’, mà phần lớn chỉ gần như là sự thể chế hóa giả làm ‘cách đúng đắn’, kèm theo những yếu tố phụ để áp đặt về mặt xã hội biến thể văn hóa sùng bái kỹ thuật mà khuôn viên đó đã phát triển tới
Tôi đã gặp vô số người rời Google dù làm ở đó rất thoải mái, vì nó lại trở thành lực cản cho sự nghiệp của họ, và con số đó không hề nhỏ
Bạn đã diễn tả chính xác sự thất vọng mà tôi trải qua ở đó. Dù vậy, tôi vẫn muốn lại được hưởng mức lương đó
Về agile, tôi biết đến nó khoảng 20 năm trước dưới dạng eXtreme Programming, và nó hoàn toàn khác với thứ cargo cult là SCRUM hay các bản bắt chước của nó ngày nay
Rốt cuộc nó là một tập hợp nguyên tắc trao quyền sáng tạo cho lập trình viên, ngăn quản lý chen vào phương pháp làm việc và để họ hoàn thành công việc. Thay vào đó, nó trao cho khách hàng quyền nói cái gì sẽ được làm, khi nào và ở mức độ nào
Lập trình viên tự ước lượng, và nguyên tắc là “không xây thứ sẽ không cần đến”. Không có thiết kế lớn từ trước; việc refactor, test, kiến trúc và thiết kế không phải là story hay task riêng, mà được tính vào overhead liên tục như những thực hành chuẩn tốt nhất
Họp kế hoạch là đồng nghiệp cùng căn chỉnh trong phòng, story được thể hiện bằng các tờ giấy ghi chú trên bảng trắng với tối thiểu thuật ngữ phi kỹ thuật. Standup thực sự là mọi người đứng thành vòng tròn và cập nhật thật ngắn, chỉ đủ để người khác có thể quan tâm, chứ không phải một nghi thức để chứng minh mình đã đi làm hôm nay hay để phô trương
Trong hệ thống này, thiết kế là một thuộc tính nảy sinh khi một tập thể sáng tạo gồm các chuyên gia cùng làm việc. Nó không loại trừ tài liệu thiết kế và vẫn có thảo luận về kiến trúc, nhưng không yêu cầu một quy trình PRD/tài liệu thiết kế minh thị
Tôi muốn lại được làm việc ở một nơi như vậy. Google thì hoàn toàn ngược lại và mọi thứ đều mất quá nhiều thời gian
Kiểu hành xử giả vờ “chúng tôi rất thông minh” này cũng là một dạng làm việc vô ích. Công ty nên tập trung vào các sản phẩm thực sự hoạt động và tự đánh giá mình bằng điều đó
Cũng là một Googler khác
Đã có nhiều bình luận hay nói rằng tài liệu thiết kế của Google là vô dụng, nhưng tôi muốn bổ sung thêm một góc nhìn về lý do nó bị xem là vấn đề
Tài liệu thiết kế, như đã nói, là tư liệu phục vụ thăng tiến nên sinh ra rất nhiều phần rườm rà. Nhưng đồng thời, nó cũng có vẻ như đang thay thế cho tài liệu hóa thực tế
Mọi tài liệu thiết kế gần như trở nên lỗi thời ngay khi hoàn thành, nhưng các nhóm lại trỏ về tài liệu thiết kế đó thay vì viết lại tài liệu mới. Kết quả là tài liệu hóa ở Google khá tệ và đã cũ kỹ
Thành thật mà nói, sẽ tốt hơn nhiều nếu tư liệu phục vụ thăng tiến là một hướng dẫn sử dụng dài 2 trang về cách dùng thứ thực sự tồn tại, thay vì 20 trang về “những việc chưa làm”
Có thể xem tài liệu thực tế không? Tài liệu về quy trình thiết kế phần mềm có vẻ là loại bí mật được giữ kín nhất. Tôi chưa từng thấy tài liệu thực tế nào có thể dùng làm nghiên cứu tình huống
Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps
Ví dụ: https://rfd.shared.oxide.computer/rfd/0177
Chỉ mục chính: https://rfd.shared.oxide.computer