- Với tiền đề rằng tài liệu kỹ thuật cần đóng những vai trò khác nhau tùy theo bối cảnh của người dùng, Diátaxis là một cách tiếp cận sắp xếp đồng thời nội dung · cấu trúc · hình thức
- Chia nhu cầu của người dùng thành 4 loại, và tương ứng với từng loại là các kiểu tài liệu tutorials, how-to guides, technical reference, explanation
- Không chỉ là một bảng phân loại đơn giản mà gần hơn với một khung thiết kế tài liệu xử lý việc nên viết gì, viết như thế nào và đặt ở đâu
- Cả người viết lẫn người bảo trì đều dễ đánh giá chất lượng tài liệu hơn, và ưu điểm là nhẹ, trực quan, không ép buộc một cách triển khai cụ thể
- Giống như các trường hợp của Vonage, Gatsby và Cloudflare, đây có thể được dùng như một tiêu chuẩn thực tiễn cho các đội ngũ muốn cải thiện khả năng điều hướng tài liệu và cấu trúc thông tin
4 loại tài liệu mà Diátaxis phân chia
- Diátaxis là một tư duy đồng thời là một phương pháp thực thi để viết và vận hành tài liệu kỹ thuật
- Điểm xuất phát là hiểu nhu cầu của người sử dụng tài liệu, từ đó rút ra các nguyên tắc về nội dung, kiến trúc và hình thức
- Nhu cầu và hình thức tài liệu được chia thành 4 loại
-
tutorials
-
how-to guides
-
technical reference
- explanation
- Bản thân tài liệu cũng cần được tổ chức xoay quanh 4 nhu cầu này, và Diátaxis đồng thời xử lý ba câu hỏi
- content: nên viết gì
- style: nên viết như thế nào
- architecture: nên tổ chức ra sao
-
Tính ứng dụng dành cho người viết và người bảo trì
- Diátaxis là một cách tiếp cận hữu ích không chỉ cho người dùng tài liệu mà còn cho cả người viết và người bảo trì tài liệu
- Nhẹ và dễ hiểu
- Dễ áp dụng một cách trực quan
- Không áp đặt các ràng buộc triển khai
- Cung cấp các nguyên tắc chất lượng để người bảo trì có thể tự đánh giá công việc của mình
- Các nguyên tắc này đã được tổng hợp từ việc áp dụng thành công trong hàng trăm dự án tài liệu
Các ví dụ dự án tài liệu thực tế
- Greg Frileux của Vonage đánh giá rằng với Diátaxis, họ có thể tạo ra một bộ tài liệu nội bộ mà người dùng thích và người đóng góp cũng dễ bổ sung
- Gatsby cho biết khi tái cấu trúc tài liệu mã nguồn mở, họ đã dùng khung Diátaxis như một nguồn tham chiếu chính, và 4 lĩnh vực này giúp ưu tiên hóa mục tiêu người dùng cho từng loại tài liệu
- Cloudflare đã dùng Diátaxis làm tiêu chuẩn cho kiến trúc thông tin khi thiết kế lại Cloudflare developer docs, đồng thời tham chiếu khung này khi xác định nội dung mới nên được đặt vào đâu
1 bình luận
Các ý kiến trên Hacker News
Ngay cả từ góc nhìn của người không viết lách chuyên nghiệp, ngoài các chi tiết cụ thể, hiểu biết quan trọng và cơ bản nhất rút ra từ đây là không nhất thiết phải nói mọi thứ đúng một lần duy nhất
Trước khi tiếp xúc với ý tưởng này, tôi từng tự làm mình rối lên vì nghĩ rằng một luồng văn bản duy nhất phải đóng vai trò là “toàn bộ tài liệu”
Chỉ cần nhận ra rằng có thể viết cùng một thông tin theo những cách khác nhau cho từng nhóm độc giả khác nhau cũng đã giúp ích rất nhiều
Vì người đọc sẽ tìm mẫu số chung giữa các ví dụ, nên cách này ít mơ hồ hơn so với việc chỉ giải thích bằng một ví dụ duy nhất
Những tác giả như Solomon trong Sách Châm Ngôn của Kinh Thánh cũng dùng kỹ thuật này rất nhiều
Trong phần tóm tắt, có thể viết “bài báo này đánh giá Y với Z và cho thấy X đúng”; trong phần mở đầu, giải thích rằng vấn đề của A quan trọng vì B nhưng khía cạnh X đã bị bỏ qua, và khi đánh giá Y thì, khác với Z, các thách thức thực tế sẽ lộ ra; rồi lại tóm lại rằng “nói ngắn gọn, vì X nên Y tốt hơn Z”
Trong phần công trình liên quan cũng tiếp tục nói rằng cách tiếp cận của Z đã cải thiện điều gì đó nhưng, như sẽ thấy ở phần sau, vẫn chưa đủ; và ở mỗi mục, thông điệp cốt lõi lại được xoay quanh rồi xử lý lại nhiều lần
Hai tuần trước tôi đã áp dụng framework này cho tài liệu của Sequin, và chỉ riêng việc có một khuôn mẫu đã rất tuyệt
Giờ luồng tài liệu đã tốt hơn nhiều, và vì biết nên đặt gì ở đâu nên việc bổ sung và bảo trì tài liệu cũng dễ hơn
Nhưng trớ trêu là bản thân tài liệu Diátaxis lại hơi khó hiểu và dài dòng, tôi phải đọc vài lần mới nắm được
Khi giải thích cho đội, tôi ví nó với việc mua một dụng cụ nấu ăn như nồi áp suất: trước tiên xem phần bắt đầu nhanh (tutorial) để biết đại khái làm sao đi từ A đến B, tiếp theo tìm cách nấu một món cụ thể mình thích, đó là how-to; khi có thắc mắc về chi tiết thì xem tài liệu tham khảo để biết thời gian nấu chính xác cho từng loại đậu; và nếu muốn biết vì sao áp suất làm thay đổi thời gian nấu hoặc cơ chế an toàn hoạt động thế nào thì đọc tài liệu giải thích
Buồn cười là tài liệu của chúng tôi từng hoàn toàn ngược lại, bắt đầu bằng những phần giải thích như “How Sequin Works”
Bản năng tự nhiên của kỹ sư là nói trước về nguyên lý hoạt động và vì sao lại làm như vậy để cài đặt một mô hình tinh thần, nhưng mọi người không có thời gian và sự kiên nhẫn cho chuyện đó
Tốt hơn là cho họ thích nghi với thế giới quan theo luồng bắt đầu nhanh → how-to → tài liệu tham khảo, rồi sau khi thật sự giành được sự quan tâm thì mới thuyết phục họ bằng tài liệu giải thích về cách tiếp cận
https://sequinstream.com/docs
Tài liệu thường hoặc trở nên mơ hồ bằng những câu nhảm nhí kiểu “trải nghiệm cộng hưởng đột phá”, như thể công ty xấu hổ khi thừa nhận công cụ của mình chỉ là một công cụ; hoặc ngược lại, đi vào chi tiết quá cụ thể trước khi bàn tới “vì sao sản phẩm này tồn tại”
Tuy vậy, trong tài liệu CDC xuất hiện lặp đi lặp lại, và tôi đã phải tìm định nghĩa. Trong sự nghiệp tôi từng triển khai CDC nhiều lần nhưng không quen với chữ viết tắt này
Luồng rốt cuộc là lựa chọn của người đọc; đầu tôi hoạt động theo kiểu muốn xem phần giải thích tổng thể trước, rồi sau đó mới tìm how-to và tutorial
Từ góc nhìn của một người viết tài liệu kỹ thuật, Diátaxis giống DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Tuy nhiên, các hệ thống như vậy có thể bỏ lỡ những gì người dùng thực sự cần
Nếu tài liệu kỹ thuật chỉ được dùng bên trong một nền tảng tài liệu, Diátaxis có thể phù hợp bền vững trong thời gian dài; nhưng nếu cùng một thông tin có thể, và nên, được dùng ở nhiều nơi như UI, cổng tài liệu, ứng dụng di động, thì có thể cần chia thông tin thành các mảnh nhỏ hơn để lắp ghép theo nhiều cách khác nhau
Điều này được gọi là tái sử dụng nội dung, tức dùng cùng một nội dung ở nhiều vị trí
Một trong các cách tiếp cận để viết và biên tập thông tin phục vụ tái sử dụng nội dung được mô tả trong khái niệm “every page is page one”: https://everypageispageone.com/the-book/
Nếu có nguồn lực và thời gian, tôi khuyên nên làm nghiên cứu UX ở giai đoạn đầu dự án. Như vậy sau này có thể tránh tình trạng ngột ngạt vì một mô hình thông tin quá hạn chế
Nielsen/Norman cũng đã nghiên cứu nhiều trong lĩnh vực này và đưa ra các đề xuất thú vị để giải quyết những vấn đề liên quan: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA phân biệt các kiểu chủ đề như task, reference, concept, nhưng tutorial hay solution guide sẽ là tổ hợp của các kiểu chủ đề đó
Ở đây có vẻ trọng tâm nằm ở các sản phẩm đầu ra lớn hơn từng chủ đề riêng lẻ
Tôi cũng tò mò liệu vì đã đi rất sâu vào DITA nên độ phức tạp có còn là vấn đề hay không
Nếu chia nội dung thành các mảnh có thể tái sử dụng và đánh dấu chúng bằng ngữ nghĩa của DITA hoặc DocBook, có vẻ các mô hình ngôn ngữ lớn sẽ dễ “hiểu” hơn nhiều, nhưng tôi chưa thấy dữ liệu liên quan
Ngày nay có những cách viết tài liệu tốt hơn là vật lộn với XSL/FO và họ hàng của nó
Trong mảng viết tài liệu kỹ thuật, cách tiếp cận này đã rất phổ biến và khá gần với chuẩn mực
Tuy nhiên đôi khi người ta đẩy nó đi quá xa, đến mức trên trang tài liệu theo đúng nghĩa đen chỉ còn bốn phạm trù này, và thường thì cách đó không hiệu quả
Nó chủ yếu hữu ích để giúp người viết giữ được suy nghĩ kiểu như “đây là một hướng dẫn, nên đừng cố dạy, hãy tập trung đưa người đọc đến kết quả”
Trong thực tế, ranh giới quá cứng nhắc là không nên, và có một chút phần tutorial trong guide cũng không sao
Theo tôi, điểm mà cách tiếp cận này thực sự bị vướng là khi thiếu liên kết giữa các góc phần tư
Ví dụ, trong tài liệu của một framework phần mềm, nếu guide không liên kết tới tài liệu tham khảo của các class hay method cụ thể mà cuối cùng người dùng phải dùng, thì việc khám phá ngữ cảnh xung quanh sẽ khó hơn nhiều
Một vài tài liệu framework cụ thể đã chia các góc phần tư theo kiểu này, và đây chính là một trong những điều gây khó chịu nhất ở các tài liệu đó
Nếu không có chuyên gia khác bên cạnh, người mới có thể nên tuân thủ quy tắc nghiêm ngặt hơn là “tự biết mà làm điều đúng”
Theo định nghĩa, người mới không có chuyên môn để đưa ra phán đoán đó, và khi tích lũy kinh nghiệm, họ bắt đầu nhìn ra những điểm cần đi chệch khỏi quy tắc đã định
Điều này giống khác biệt giữa nấu cơm nhà theo sách dạy nấu ăn và một đầu bếp chuyên nghiệp ném nguyên liệu vào nồi theo cảm giác và khẩu vị
Nhưng tôi từng làm việc với người khăng khăng rằng trong tutorial không được có dù chỉ một câu giải thích, và phải làm theo quy tắc đúng từng chữ
Nguy cơ của những hệ thống như vậy nằm chính ở đó
Nó giống các nguyên tắc lập trình như “đừng thay đổi biến toàn cục” hay “hãy viết hàm ngắn”
Không cần phải làm đúng hoàn hảo, nhưng phần lớn trường hợp thì đi theo hướng đó vẫn tốt hơn là hướng ngược lại
Vì vậy tôi đã nhờ Claude phân loại phần đầu theo Diátaxis, và nó trả lời rằng phần đó chủ yếu là giải thích, có pha một số yếu tố tham khảo, và theo tiêu chí Diátaxis thì không lý tưởng
Nó nói tốt hơn nên tách thành một phần chỉ giải thích khái niệm và tầm quan trọng của việc tinh chỉnh siêu tham số, cùng một phần tham khảo riêng liệt kê các công cụ và phương pháp có thể dùng
Nhưng sau đó nó cũng tóm tắt vì sao cách tiếp cận tích hợp này lại hiệu quả trong bối cảnh user guide: nó đi theo luồng học thực tế của con người, nối khái niệm với triển khai ngay lập tức, hé lộ dần từ khái niệm cơ bản đến công cụ phức tạp, và đem lại giá trị thực tiễn bằng cách nối lý thuyết với thực hành
Với tư cách là người vừa hoàn tất phát hành ứng dụng SwiftUI đầu tiên, tôi cảm nhận rất mạnh rằng trong ngành công nghệ hiện đại, tài liệu hóa đang bị xem nhẹ quá mức
Tôi vô cùng nhớ công việc của những technical writer xuất sắc mà Apple đã sa thải, còn các kỹ sư Apple thì thật sự viết tài liệu rất kém
Tuy vậy, tôi luôn thận trọng với các cách tiếp cận “giáo điều”. Rất dễ xuất hiện một “tầng lớp tư tế” không chịu uốn theo yêu cầu của thực tế
Những người đầu tiên tạo ra giáo lý đó có thể vận dụng nó rất giỏi, nhưng các “tư tế” đi sau lại làm hỏng và biến cách tiếp cận thành một lời nguyền
Rất nhiều ý tưởng hay đã bị phá hỏng vì áp dụng quá cứng nhắc. Chỉ cần nhìn xem “Agile” đã trở thành thứ gì là đủ
Về cơ bản tài liệu có hai gương mặt: maintainer và user, và hai nhóm này có nhu cầu rất khác nhau, nên có lẽ cần được xử lý bởi những đội hoàn toàn khác nhau
Cũng có vấn đề tài liệu ở nhiều nơi bị lệch đồng bộ, nhưng điều quan trọng là kết quả
Nếu có thể đồng bộ hiệu quả nhiều instance, tài liệu sẽ hiệu quả và hữu ích cho người tiêu thụ
Tài liệu được định dạng và đồng bộ hoàn hảo mà không ai đọc thì cũng không có giá trị
The Anal-Retentive Chef do Phil Hartman đóng trên SNL dành quá nhiều thời gian cho khâu chuẩn bị đến mức không thể thực sự trình diễn nấu ăn, và trong lĩnh vực công nghệ tôi cũng thấy rất nhiều hình ảnh như vậy
Có những toolchain và thư viện hoàn hảo nhưng thực tế lại không dùng được
Tài liệu là sự pha trộn của nhiều lĩnh vực: bản chất và tâm lý con người, thiết kế đồ họa, cấu trúc thông tin, hạ tầng kỹ thuật, xuất bản và phân phối
Trong hầu hết dự án, tài liệu bị xem như chuyện để sau, nhưng tôi nghĩ nó phải là một mối quan tâm hạng nhất ngay từ giai đoạn yêu cầu
Có thể đào sâu cấu trúc tài liệu đến vô tận, nhưng cho đến khi tìm ra chỗ rò rỉ, nó đóng vai trò như một bộ bánh phụ tuyệt vời
Nghe như thể những hiểu lầm phổ biến hoặc cách áp dụng sai một ý tưởng hay sẽ làm hỏng chính ý tưởng đó
Ngược lại, có kinh nghiệm thu được từ việc áp dụng thực tế. Nếu ban đầu ý tưởng thực ra không tốt, thì đó là phá vỡ ảo tưởng; còn các ví dụ tệ, nếu diễn giải sai dẫn đến thất bại, sẽ bộc lộ những điểm mơ hồ và giúp ý tưởng được tinh chỉnh hơn
Tuy nhiên, nếu ngày càng nhiều người quen với các triển khai tệ, mức độ phổ biến của ý tưởng có thể giảm, và nhu cầu đối với các triển khai tinh tế cũng giảm theo
Điều này gần với bi kịch phản công hữu hơn là sự thoái hóa của chính ý tưởng
Diátaxis rất tốt cho việc cấu trúc tài liệu, nhưng giá trị thật sự của nó nằm ở chỗ đơn giản hóa cách viết tài liệu
Nó giúp ta thoát khỏi ý nghĩ phải nhồi mọi thứ vào một “tài liệu hoàn hảo” duy nhất, và nhận ra rằng mỗi người dùng có nhu cầu khác nhau
Tutorial là để học bằng cách làm theo, guide là để giải quyết một vấn đề cụ thể, reference là để tra cứu nhanh, còn explanation là để đào sâu vào “vì sao”
Chỉ riêng sự rõ ràng này cũng có thể giúp viết ra tài liệu hữu ích
Tuy nhiên, bất kỳ hệ thống nào nếu bám quá chặt cũng sẽ trở thành cái bẫy
Hoặc không biết liệu có một mô hình thống nhất nào không
Tổ chức của chúng tôi đang dùng cách này, và kể từ khi áp dụng, tài liệu kỹ thuật đã lên một đẳng cấp hoàn toàn khác
Cộng thêm quyền sở hữu trang và việc các chủ sở hữu trang định kỳ rà soát, đây đã trở thành nỗ lực tài liệu hóa kỹ thuật thành công duy nhất mà tôi từng thấy
Tôi thấy sơ đồ mà divio dùng trực quan hơn nhiều: https://docs.divio.com/documentation-system/
Tuy vậy, phía Diátaxis dường như đã ghi chép bao quát hơn về từng ý nghĩa
Bản viết lại Divio trên Diataxis.fr có đồ họa ít rối hơn, nhưng về bản chất tôi thấy vẫn giống cái Divio từng dùng
Tôi vẫn xem hai tài liệu này, xét về các ý tưởng được trình bày trong ngữ cảnh website của mỗi bên, về cơ bản là cùng một tài liệu
Muốn biết điểm nào khiến nó trực quan hơn
Tôi thích ý tưởng này, và cũng may mắn được gặp người tạo ra nó vài lần ở PyConUK. Đó là một người tài năng và rất tử tế
Tuy nhiên, tôi vẫn dè dặt với việc phân tách các mảng tài liệu nghiêm ngặt đến mức này
Có lần trong một sprint, tôi được nói rằng tài liệu tôi đang chuẩn bị là không thể chấp nhận vì nó pha trộn nhiều dạng thức. Nhân tiện, đó không phải là điều Daniele nói
Tôi không định viện dẫn uy quyền, nhưng tôi đã làm giáo viên hơn 20 năm, và cũng có chút cảm nhận về cách giải thích cũng như tạo giàn giáo học tập để mọi người vừa hoàn thành việc vừa xây dựng được hiểu biết
Miễn là không quá cứng nhắc, đây là một công cụ tuyệt vời để quyết định cách xây dựng tài liệu và mỗi loại tài liệu nên làm gì
Tôi thường thấy các ví dụ trong tài liệu, chẳng hạn ở numpy, có thể được chọn tốt hơn nhiều thay vì kiểu ví dụ “ma thuật từ trên trời rơi xuống”
Một ví dụ được chọn tốt có thể vừa cho thấy cách dùng, vừa cung cấp rất nhiều kiến thức về các trường hợp biên hoặc những điểm cần lưu ý
Về lý thuyết thì tôi nghĩ là đúng, nhưng khó mà đồng ý. Các từ quá gần nhau
Với tôi, “tutorial”, “how-to guide”, “explanation” thực tế gần như là từ đồng nghĩa
Nếu nghĩ kỹ thì tôi hiểu mỗi phạm trù đều có lý do chính đáng, nhưng về mặt ngữ nghĩa chúng quá gần nhau nên đầu óc tôi không thấy được khác biệt
Khi muốn biết một thứ hoạt động như thế nào mà thấy “tutorial” và “how-to guide”, tôi không biết nên bấm vào đâu và cuối cùng chỉ bấm cái đầu tiên
Tìm những thuật ngữ phù hợp hơn với mình cũng có thể là một bài tập hữu ích
Hoặc có thể hiểu theo trục hành động/nhận thức, tức “làm vs suy nghĩ”, và tiếp thu/áp dụng, tức “đang học vs đang làm việc”
Cũng có một trang riêng phân biệt tutorial và how-to guide: https://diataxis.fr/tutorials-how-to/
Một trong những cách phân biệt đơn giản nhất là tutorial là thứ bạn không thể làm trên Stack Overflow
Tutorial là quá trình đi theo giáo án do giáo viên định sẵn, lấp vào cả những phần mà học viên còn không biết là mình chưa biết
Trên Stack Overflow bạn phải đặt câu hỏi, còn tutorial là tài liệu dành cho người thậm chí chưa biết mình nên hỏi gì
Có rất nhiều câu hỏi phổ biến về cách làm các tác vụ đơn giản, nhưng để phù hợp với định dạng đó, bạn phải đặt câu hỏi chứ không phải chỉ mơ hồ xin giúp đỡ: https://meta.stackoverflow.com/questions/284236
Tài liệu Diátaxis giải thích khác biệt khá hiệu quả: tutorial là trải nghiệm hướng tới học tập, how-to guide là chỉ dẫn hướng tới mục tiêu, tài liệu tham khảo là mô tả kỹ thuật hướng tới thông tin, còn explanation là thảo luận hướng tới hiểu biết
Trong hệ thống này, nên đọc “tutorial” như một thuật ngữ chuyên môn, chứ không phải từ thông dụng hằng ngày
Tương tự như “depression” mà nhà tâm lý học nói đến không hoàn toàn giống nghĩa đời thường
Dù vậy vẫn tốt hơn là gọi chúng là tutorial Type I-IV
Bài giảng là explanation, tutorial hay bài thực hành là trải nghiệm có hướng dẫn, và làm tôi nhớ đến công ty giả Contoso của Microsoft
How-to guide là thứ bạn cần khi tìm kiếm giải pháp hoặc hỏi ChatGPT, còn tài liệu tham khảo giống như từ điển đồng nghĩa, bách khoa toàn thư, sách hướng dẫn sử dụng
Trò chơi điện tử có tutorial tích hợp, nhưng với câu đố khó vẫn cần walkthrough, còn thiết lập phím thì tra trong tài liệu tham khảo