Cách viết tài liệu thiết kế tốt

• Tài liệu thiết kế là một báo cáo kỹ thuật tổng hợp chiến lược triển khai, các ràng buộc và những đánh đổi của hệ thống
• Tài liệu thiết kế có vai trò thuyết phục người đọc rằng thiết kế đó phù hợp với bối cảnh
• Cấu trúc của tài liệu rất quan trọng; cần có luồng logic để người đọc không bị bất ngờ bởi nội dung
• Cần biên tập để giảm bớt từ ngữ không cần thiết và tiết kiệm nguồn lực tập trung của người đọc
• Việc dùng đoạn ngắn, phụ lục và rèn luyện để nâng cao năng lực viết tài liệu là rất quan trọng

---

Định nghĩa

• Tài liệu thiết kế là một báo cáo kỹ thuật tổng hợp chiến lược triển khai hệ thống trong bối cảnh các đánh đổi và điều kiện ràng buộc

Mục tiêu

• Tài liệu thiết kế có mục đích thuyết phục người đọc rằng thiết kế này là tối ưu, giống như một chứng minh trong toán học dùng để khiến người đọc chấp nhận một định lý
• Trong quá trình thiết kế, bản thân việc viết ra cũng làm tăng độ chặt chẽ trong tư duy
• Viết tài liệu thiết kế giúp biến những suy nghĩ mơ hồ thành tư duy cụ thể

Tổ chức

• Cấu trúc của một tài liệu thiết kế tốt quan trọng không kém việc tổ chức mã nguồn
• Cũng như người mới viết code, nhiều người có xu hướng tạo ra "tài liệu thiết kế spaghetti"
• Nếu chỉ liệt kê các câu mà không có trình tự logic, người đọc sẽ khó theo kịp ngữ cảnh và dễ bị rối
• Một tài liệu hoàn chỉnh cần có luồng tự nhiên để người đọc không bị bất ngờ, và mỗi câu phải nối tiếp một cách hiển nhiên dựa trên nội dung trước đó
• Mục tiêu là nắm được trạng thái tư duy của người đọc và dẫn dắt họ từng bước sang một trạng thái mới
• Cần giải tỏa trước các phản biện có thể dự đoán được, tức là giải thích trước khi người đọc kịp nêu phản đối

Biên tập

• Sau khi đã tổ chức nội dung tốt, bước loại bỏ từ ngữ không cần thiết (biên tập) là rất quan trọng
• Khả năng tập trung của người đọc là một nguồn lực hữu hạn, nên cần mạnh dạn xóa bỏ thông tin không cần thiết
• Trong bản nháp, có thể cắt giảm khoảng 30% những cách diễn đạt vô nghĩa
• Khi biên tập tài liệu của người khác và rèn luyện góc nhìn phản biện, bạn cũng có thể chỉnh sửa bài viết của chính mình hiệu quả hơn
• Luyện tập bằng tweet ngắn (giới hạn 280 ký tự) cũng giúp đơn giản hóa tư duy và cải thiện khả năng cô đọng

Kinh nghiệm và luyện tập

• Không có con đường tắt nào để nâng cao kỹ năng tốt hơn luyện tập lặp đi lặp lại
• Trải nghiệm với văn hóa lấy tài liệu làm trung tâm tại Amazon đã giúp cải thiện đáng kể năng lực viết tài liệu
• Trong các cuộc họp quan trọng, người ta phát tài liệu thiết kế dài từ 1 đến 6 trang, sau đó mọi người đọc trong im lặng và ghi ý kiến vào lề
• Nhận phản hồi là cách thiết thực để nâng cao kỹ năng viết

Mẹo cụ thể

Dùng đoạn ngắn

• Tài liệu thiết kế nên tạo luồng bằng các bullet point ngắn gọn nối tiếp nhau
• Mỗi bullet point (quan sát, ý tưởng, vấn đề, cải tiến, v.v.) nên là một đoạn ngắn tập trung vào một khái niệm
• Mỗi đoạn cần đủ rõ ràng để có thể tóm tắt bằng một câu, nhờ đó tiết kiệm nguồn lực trí nhớ ngắn hạn của người đọc

Tận dụng phụ lục

• Các phép tính phức tạp hoặc kết quả mô phỏng nên được trình bày chi tiết trong phụ lục thay vì phần thân tài liệu, còn trong thân bài chỉ nên nhắc ngắn gọn như chú thích
• Phụ lục không phải là phần bắt buộc để hiểu các kết luận chính của tài liệu, mà được cung cấp để người đọc quan tâm có thể tham khảo

Ví dụ biên tập

• (Trước khi biên tập, đoạn văn dài dòng):

  Mỗi bullet point nên trở thành một đoạn riêng trong tài liệu. Mỗi đoạn cần có thể được tóm tắt bằng một câu. Không nhất thiết nó phải thực sự chỉ là một câu, vì có thể cần thêm giải thích để làm rõ khái niệm. Nhưng sau khi đọc, người đọc phải có thể tóm tắt nó bằng một câu.

• (Sau khi biên tập, đoạn văn đã được cô đọng):

  Mỗi bullet point nên là một đoạn và có thể được tóm tắt bằng một câu. Nó không nhất thiết phải chỉ là một câu, và nếu cần thì có thể thêm giải thích. Nhưng sau khi đọc xong, nó phải có thể được nén lại thành một câu.

Kết luận

• Tài liệu thiết kế là một quy trình quan trọng giúp nâng cao độ chặt chẽ trong tư duy, luồng logic, biên tập hướng đến người đọc và năng lực thông qua luyện tập lặp lại

[GN⁺]

Ý kiến Hacker News

• Bài viết có hai câu trích dẫn đặc biệt gây ấn tượng. Câu đầu là từ ảnh chụp màn hình trên X: "ý tưởng trở nên tốt hơn gấp 10 lần trong quá trình viết". Câu thứ hai là ở phần mở đầu: "người quan trọng nhất cần được thuyết phục chính là bản thân tác giả". Thật ngạc nhiên khi dù đã làm việc trong ngành nhiều năm, vẫn có những người phản đối sự cần thiết của tài liệu thiết kế. Leslie Lamport từng nói rằng "viết lách là cách tự nhiên cho ta biết tư duy của mình cẩu thả đến mức nào". Nếu muốn cải thiện hơn nữa kỹ năng viết kỹ thuật, tôi khuyên nên đọc bài Write Like an Amazonian(https://medium.com/@apappascs/…)
  • Có lẽ vì lời khuyên kiểu "hãy biến tính từ thành dữ liệu" đã lan khắp ngành kỹ thuật, nên dạo này CV nào tôi xem cũng đầy số liệu đến mức khó hiểu rốt cuộc chúng có ý nghĩa gì
• Với tư cách là người review thiết kế, có một điều mà mọi người viết tài liệu đều phải thực sự thấm nhuần. Đó là đoạn: "một tài liệu tốt giúp người đọc hiểu được vấn đề và mô hình tư duy, để khi giải pháp được đưa ra sau nhiều tuần suy nghĩ, họ sẽ tự nhiên thấy thuyết phục". Câu trích dẫn tôi thích nhất là: "nếu có thêm thời gian, tôi đã viết một lá thư ngắn hơn". Tôi nghĩ tài liệu thiết kế phải làm cho nội dung phức tạp trở nên đơn giản, chứ không phải nơi đổ hết mọi khúc quanh và thất bại mà lập trình viên đã trải qua. Những nội dung đó tất nhiên cũng đáng ghi lại, nhưng nên được sắp xếp vào tài liệu riêng hoặc phụ lục. Cần cho thấy con đường tiến tới phía trước một cách đơn giản
  • Tôi thích cách diễn đạt "nhiều thời gian hơn, lá thư ngắn hơn" hơn
  • Tôi luôn tự hỏi mình những câu như: "Chủ đề này có dễ phát sinh tranh cãi vô ích không?", "Cuộc tranh cãi đó có đáng để diễn ra không?" Mục tiêu của tôi là để người đọc mới có thể tham gia thảo luận mà không gặp khó khăn, đồng thời tránh gây tranh cãi ở những phần không quan trọng
• Các cuộc họp ở Amazon bắt đầu bằng việc người trình bày phát tài liệu viết theo văn xuôi. Mọi người ngồi yên lặng đọc tài liệu, ghi chú và câu hỏi bằng bút đỏ ở lề. Tôi chưa từng thực sự làm việc tại Amazon, nhưng cách này hiệu quả đến mức đáng kinh ngạc, và những người kể về trải nghiệm đó dường như đều rất thích. Thoạt nhìn có vẻ lãng phí khi dành thời gian họp quý giá chỉ để cùng đọc, nhưng nếu đọc và chuẩn bị trước thì lẽ ra có thể họp ngắn hơn. Việc cùng đọc theo thời gian thực khiến mọi người phải chờ người đọc chậm hơn, hoặc vì thiếu ngữ cảnh nên mức độ hiểu khác nhau, thành ra thời gian trôi qua một cách mơ hồ. Khi review thiết kế ở Google, tôi thường thấy phần lớn người tham dự tham gia thảo luận trong khi lần đầu tiên mới đọc tài liệu. Tôi nghĩ điều này là vì Google không có văn hóa tài liệu mạnh, và việc team lead hay manager đến mà không chuẩn bị cũng được ngầm chấp nhận. Chỉ cần hình thành được văn hóa bắt buộc đọc kỹ trước cuộc họp thôi thì thời gian họp đã có thể được dùng hiệu quả hơn rất nhiều
  • Người ta nói rằng nếu đọc trước cuộc họp thì thời gian họp sẽ giảm, nhưng thông lệ của Amazon là cách ứng phó với thực tế rằng mọi người trên thực tế sẽ không đọc trước. Trong một bài viết liên quan trước đây, có nói rằng việc tạo ra văn hóa chuẩn bị trước mạnh mẽ trên thực tế gần như là bất khả thi. Mọi người tham dự đều không thể chuẩn bị trước vì còn cuộc họp ngay trước đó, mà trước cuộc họp đó lại còn cuộc họp khác nữa. Về lý thuyết có thể chỉ trích rằng vậy sao không giảm số cuộc họp đi, nhưng trên thực tế các cuộc họp đó vẫn có giá trị, và ngay cả khi tính cả thời gian đọc thì quyết định vẫn được đưa ra đầy đủ. Rốt cuộc cần tập trung vào kết quả, và có vẻ ở Amazon, người ta thật sự cảm thấy lợi ích của cách làm này lớn hơn bất lợi
  • Tôi thắc mắc vì sao việc đọc tài liệu vào lúc nào lại quan trọng. Nếu cần thêm thời gian thì có thể kéo dài thời lượng họp. Điểm bất lợi là khó sắp lịch họp hơn, nhưng có ý kiến cho rằng tổng thời gian bỏ ra thì không đổi
  • Tôi nghĩ việc mọi người không cùng một mức hiểu biết, hoặc lo rằng ai đó sẽ bỏ sót corner case, mới là thứ gây lãng phí thời gian nhiều hơn
  • Có người chia sẻ trải nghiệm rằng nếu không được đưa vào cuộc họp xử lý thì sẽ chẳng có gì xảy ra cả
• Có rất nhiều lời khuyên tuyệt vời về tính rõ ràng và việc biên tập. Điểm yếu là sau khi tài liệu được phê duyệt thì quản lý nó như thế nào. Nếu không có quản lý, nó sẽ thoái hóa thành trạng thái "khảo cổ thiết kế". Vài năm trước Andrew Harmel-Law đã đề xuất Architecture Decision Records(ADRs) như một cách ghi lại hiệu quả các quyết định kiến trúc trong tổ chức, và cách này có thể hữu ích. ADRs được đặt cạnh mã nguồn (ví dụ: adr/001-use-postgres.md) và ghi ngắn gọn bối cảnh, quyết định, cùng trạng thái. Vì vậy chúng dễ được review trong mỗi PR, dễ được thay thế khi tình hình thay đổi, và lý do của quyết định ban đầu vẫn có thể tra cứu được sau nhiều tháng. [Liên kết: https://martinfowler.com/articles/…]
  • Với cách này thì không biết các ủy ban toàn tổ chức về Security, Privacy, Compliance... có trở thành reviewer cho mọi PR có gắn ADR hay không. Tôi nghi ngờ những PR như vậy có thể được merge trong vòng 90 ngày hay không
  • Tôi cần đọc kỹ toàn bộ liên kết MF.com(https://thoughtworks.com/radar/techniques/…), nhưng "Advice Process" lại kết thúc bằng câu kiểu 'hãy nói chuyện với mọi người'. Người mang chức danh có chữ 'Managing' có lẽ sẽ mất hứng từ đây. Cốt lõi thực sự là "bốn yếu tố hỗ trợ", và khi tôi vào liên kết này để tìm hiểu thêm về ADRs, cuối cùng tôi lại bị dẫn tới PDF(https://thoughtworks.com/content/dam/…). Sẽ tốt hơn nếu có một định nghĩa rõ ràng về ADRs thực sự là gì
  • Session messenger là một ví dụ tiêu biểu. Đã có vô số thay đổi về thiết kế và kiến trúc nên không còn thông tin mang tính thẩm quyền nào giải thích chính thức cách nó hoạt động. Nhân tiện, nếu cần nhắn tin bảo mật thì cứ dùng Signal là được
• Theo kinh nghiệm của tôi, tổ chức ý tưởng và sự rõ ràng là trở ngại lớn nhất khiến kỹ sư SW khó cải thiện kỹ năng viết tài liệu. Phép so sánh "mì spaghetti mã nguồn" của tác giả là ví dụ hay để giải thích tầm quan trọng của việc tổ chức ý tưởng. Tôi cũng từng cố truyền đạt điều tương tự theo cách khác, và từ giờ có lẽ tôi sẽ dùng phép so sánh này. Trước đây tôi từng viết một bài blog tương tự (https://ryanmadden.net/things-i-learned-at-google-design-docs/), và thấy thú vị ở các điểm chung như mật độ thông tin, tầm quan trọng của thực hành, cũng như những khác biệt tùy công ty. Về quan điểm "đoạn văn ngắn" thì tôi hơi khác ý. Đoạn văn ngắn chỉ xuất hiện khi thông tin đã được gọt giũa tốt; chỉ xuống dòng thôi thì không giúp ích gì. Tôi nghĩ phần "Editing" giải thích rõ hơn ý nền tảng đó
• Tôi có một quy trình mình hay dùng. Bước 1: đổ tất cả những gì nghĩ ra vào tài liệu theo cách lộn xộn nhất có thể (thử đọc chính tả bằng giọng nói cũng được). Bước 2: dùng LLM để thử tạo cấu trúc và dòng chảy. Thực ra ở bước này có thể bỏ luôn kết quả đi, vì đây vẫn là quá trình tiếp tục gọt ý. Bước 3: tham khảo kết quả từ LLM hoặc tự lập outline mới hoàn toàn để viết bản nháp đầu tiên. Bước 4: rút bớt từ ngữ, thay bằng từ dễ hơn, nói chung là làm cho ngắn gọn tối đa. Bước 5: lặp lại bước 4. LLM đóng vai trò như cây cầu giúp cấu trúc một bản nháp rời rạc. Cũng cần sẵn sàng vứt bỏ những gì LLM tạo ra. Luôn có thể cắt ít nhất 30%. Mỗi lần thấy có thể rút gọn mà không mất nghĩa, tôi lại thấy ngạc nhiên
  • Tôi cảm thấy quá trình biên tập lại bài viết của mình quan trọng không kém gì lúc viết nó lần đầu. Đây là lúc tôi nhận ra mình đã kết luận vội vàng đến đâu, hoặc đã bỏ sót những điểm gì. Có vẻ nhiều người chưa đánh giá đúng mức giá trị của viết lách như một công cụ tập trung tư duy. Với code cũng vậy. Kể cả chỉ viết phần khung đi nữa, nhiều khi lúc viết test code tôi lại nảy ra ý tưởng để cải thiện main code. Nhưng LLM không chỉ ra cho bạn những cơ hội cải thiện mang tính định tính như thế
  • Mở rộng, rút gọn, nén lại, rồi lại mở rộng, rồi lại nén tiếp. Khi ai đó đặt câu hỏi cụ thể thì lại mở rộng thêm, và cuối cùng dùng LLM để tạo một bản tóm tắt vui vẻ cho đỡ áp lực. Chúng ta đúng là đang ngồi trên một chuyến tàu lượn siêu tốc không có hồi kết
• Tôi nghĩ mình cần viết nhiều hơn. Hai cách cấu trúc tài liệu tiêu biểu mà tôi nghĩ tới là B.O.O. và Good Strategy/Bad Strategy. B.O.O. là viết tắt của Background, Objective, Overview, tức là sắp xếp lại quá trình đi đến hiện tại và những gì muốn thay đổi, bằng cách nào. Good Strategy/Bad Strategy là một cuốn sách gồm chẩn đoán, guideline/tiền đề/yêu cầu, và hành động; xét về mặt tổ chức tài liệu thì khá giống B.O.O.. B.O.O. phù hợp với Google hoặc các tổ chức nhỏ về mặt con người, còn Good Strategy/Bad Strategy áp dụng được cho quy mô đa dạng hơn nhiều nhưng đòi hỏi tác giả có năng lực viết tốt
• Khi học lớp viết kỹ thuật, khả năng tóm tắt rõ ràng ý chính của tôi đã cải thiện rất nhiều. Lớp học tập trung vào kiểu "cắt bằng bút đỏ" (viết ra, gạch bớt, rồi viết lại), nhấn mạnh cách truyền đạt khái niệm bằng ít từ nhất có thể. Quá trình này gồm nhiều giai đoạn, và càng luyện tập thì càng dễ hơn. Tôi cũng cố chia sẻ năng lực này với các thành viên trong nhóm, nhưng luôn tự nhắc mình rằng đây là kỹ năng cần được rèn thường xuyên
• Tôi thực sự thích những tài liệu được viết theo kiểu này và cả văn hóa viết lách đó. Nhưng tôi cũng từng thấy cách tiếp cận này phản tác dụng. Việc giải thích lý do và logic dẫn tới kết luận rất hiệu quả với tài liệu mang tính thuyết phục. Tuy nhiên, không phải lúc nào cũng cần kiểu thuyết phục như vậy. Đôi khi viết thẳng kết luận trước lại tốt hơn cho người đọc, đặc biệt là những người đã tin tưởng tác giả. Trong nhiều trường hợp, người đọc muốn biết ý chính trước hơn là mệt mỏi vì phải lần theo toàn bộ lập luận. Khi đã biết kết luận rồi, lúc đó họ mới muốn đi tiếp vào chi tiết logic
  • Việc đặt phần tóm tắt ở trên và nối tiếp bằng giải thích chi tiết cùng căn cứ ở dưới cũng hoàn toàn ổn
• Đôi khi tôi tự viết tài liệu thiết kế dù có thể chỉ mình tôi đọc. Chỉ riêng việc để lại suy nghĩ dưới dạng văn bản cũng đã rất mạnh mẽ. Nếu có tài liệu mẫu thực tế thì sẽ cực kỳ hữu ích; tôi muốn so sánh cấu trúc tài liệu của mình với cấu trúc cuối cùng của người khác