- Diátaxis là một khái niệm đưa ra cách tiếp cận có hệ thống đối với việc viết tài liệu kỹ thuật. Cách tiếp cận này bắt đầu từ việc tiếp cận một cách có hệ thống để hiểu nhu cầu của người dùng tài liệu, rồi đề xuất phương thức tiếp cận về nội dung, cấu trúc và hình thức.
- Bắt nguồn từ tiếng Hy Lạp cổ, Diátaxis xác định bốn nhu cầu rõ ràng và các dạng tài liệu tương ứng là hướng dẫn từng bước, hướng dẫn cách làm, tham chiếu kỹ thuật, và giải thích. Phương pháp này đề xuất tổ chức tài liệu theo cấu trúc của những nhu cầu đó.
- Diátaxis giải quyết các vấn đề liên quan đến nội dung (viết gì), phong cách (viết như thế nào), và cấu trúc (tổ chức ra sao) của tài liệu.
- Nó không chỉ có giá trị với người dùng tài liệu mà còn với người viết và người bảo trì tài liệu. Nhẹ nhàng, dễ hiểu và đơn giản để áp dụng. Nó không áp đặt các ràng buộc triển khai, mà cung cấp những nguyên tắc chủ động giúp nâng cao chất lượng tài liệu.
Nội dung
-
Trang web này được chia thành hai phần chính để hỗ trợ áp dụng và hiểu về Diátaxis.
- Bắt đầu từ đây. Các trang này giúp hiểu ngay lập tức và cụ thể về cách tiếp cận.
- Áp dụng Diátaxis
- Hướng dẫn từng bước
- Hướng dẫn cách làm
- Tham chiếu
- Giải thích
- La bàn
- Quy trình làm việc
- Phần này đi sâu hơn vào lý thuyết và các nguyên tắc của Diátaxis, đồng thời trình bày sự hiểu biết về các nhu cầu làm nền tảng cho nó.
- Tìm hiểu Diátaxis
- Nền tảng
- Bản đồ
- Chất lượng
- Hướng dẫn từng bước và hướng dẫn cách làm
- Tham chiếu và giải thích
- Cấu trúc phân cấp phức tạp
- Bắt đầu từ đây. Các trang này giúp hiểu ngay lập tức và cụ thể về cách tiếp cận.
-
Diátaxis là một nguyên tắc đã được kiểm chứng trong thực tiễn. Nó đã được áp dụng thành công trong hàng trăm dự án tài liệu.
- Tại Gatsby, khi tái cấu trúc tài liệu mã nguồn mở, họ sử dụng khung Diátaxis như một nguồn lực chính. Bốn góc phần tư giúp ưu tiên mục tiêu của người dùng đối với từng loại tài liệu.
- Khi thiết kế lại tài liệu dành cho nhà phát triển của Cloudflare, Diátaxis đã trở thành ngôi sao Bắc Cực của cấu trúc thông tin. Bằng cách tham chiếu khung này khi quyết định vị trí của nội dung mới, tài liệu trở nên rõ ràng hơn cho cả độc giả lẫn người đóng góp.
1 bình luận
Ý kiến trên Hacker News
Một người dùng cho biết điều quan trọng là nhận ra không cần truyền tải mọi thông tin trong một lần. Việc viết thông tin theo nhiều cách khác nhau cho nhiều nhóm độc giả là rất hữu ích
Có ý kiến cho biết việc áp dụng framework Diátaxis vào tài liệu của Sequin đã giúp cải thiện luồng tài liệu. Tuy nhiên, bản thân tài liệu về Diátaxis lại hơi khó hiểu và dài dòng
Những người viết tài liệu kỹ thuật cho biết Diátaxis tương tự DITA. Tuy nhiên, nó có thể bỏ sót nhu cầu của người dùng, và cũng cần chia nhỏ thông tin để tái sử dụng nội dung
Một người dùng phát triển ứng dụng SwiftUI cảm thấy tài liệu kỹ thuật hiện đại đang bị làm sơ sài, và cho rằng tài liệu cần tính đến cả hai góc nhìn: người bảo trì và người dùng
Có ý kiến cho rằng Diátaxis hữu ích trong việc cấu trúc tài liệu, nhưng nếu áp dụng quá cứng nhắc thì có thể trở thành cái bẫy
Có ý kiến giải thích rằng giá trị thực sự của Diátaxis nằm ở việc đơn giản hóa cách viết tài liệu. Điều quan trọng là viết tài liệu phù hợp với nhu cầu của từng người dùng
Có người nhận xét đồ họa của divio trực quan hơn, nhưng Diátaxis cung cấp tài liệu toàn diện hơn
Có ý kiến cho biết sau khi áp dụng Diátaxis, tài liệu kỹ thuật đã được cải thiện đáng kể, đồng thời quyền sở hữu trang và việc rà soát định kỳ cũng góp phần vào thành công của công tác tài liệu hóa
Có ý kiến cho rằng framework Diátaxis cung cấp một cấu trúc đơn giản, dễ hiểu nên rất hữu ích cho việc viết tài liệu kỹ thuật
Có người đang dùng Diátaxis để viết tài liệu cho Logdy và muốn hỏi ý kiến liệu phương pháp này có hữu ích để tài liệu hóa sản phẩm phần mềm hay không. Họ cho biết đã truyền đạt cách sử dụng sản phẩm hiệu quả thông qua các bài blog