我不贊同 Diátaxis 架構

原本是寫在技術寫作的相關重點裡面的，不過越寫越長乾脆就把他變成一篇文章了。

Diátaxis

做了越多功課之後越不贊同 Diátaxis 結構。他雖然沒有直接說出四個象限就必須照順序寫，但是他自己的說明、編排和單向迴圈的圖示，實際上已經非常明示該這樣寫了。

This phrase should not be understood too literally. It is not the case that a user must encounter the different kinds of documentation in the order tutorials > how-to guides > technical reference > explanation. In practice, an actual user may enter the documentation anywhere in search of guidance on some particular subject, and what they want to read will change from moment to moment as they use your documentation. However, the idea of a cycle of documentation needs, that proceeds through different phases, is sound and corresponds to the way that people actually do become expert in a craft."
翻譯：這句話不應該被理解得太過字面。並不是說使用者必須依照教學文件 > 操作指南 > 技術參考 > 說明解析的順序來接觸這些不同種類的文件。實際上，真正的使用者可能從文件的任何一處進入，尋求某個特定主題的指引，而他們想要閱讀的內容也會隨著使用文件的過程而時時改變。然而，文件需求存在一個循環，會依序經歷不同階段，這個概念是成立的，也符合人們實際習得一門技藝專長的方式。

這句話的意思是

用戶不見得會照順序讀（表示文檔已經照順序排了）
文件需求存在循環
現實世界人類就是照這個順序學的
旁邊的圖片也用箭頭指向單向迴圈順序

總不會連續講了三次順序，圖也畫箭頭順序，最後的結論是不推薦照順序編排吧？？（note: 如果他會寫出這種句子連續提起順序，圖片也畫了順序，結果意思是說不是喔，我沒有建議你照這個順序喔，那表示他連自己的文檔寫的極度糟糕混淆讀者模稜兩可。因此反過來說，這句話的意思絕對應該要被理解成照順序排）。所以 Diátaxis 就是建議要照順序編排，否則就是文字錯和圖錯二選一。

但是如果 Diátaxis 的迴圈編排文章，就代表用戶會在完全不懂自己在幹嘛的情況下，做了操作，看了 reference，最後才知道背後的道理，這是非常令人困惑的學習方式。你可以想想看你的數學老師完全不教你發明對數是想解決什麼問題，這是利用數學什麼工具，定義了什麼內容，只教你把對數公式背出來解題，那你會有多茫然：你會算、你會做，但是你不知道自己在幹嘛，根本就是虛的。

再講切分，如果你真的要照他的要求切，那同一份概念就會重複在 how-to、reference、explanation 重複出現，不只文檔維護者難以維護，內容重複用戶也看不下去。

如果提升層級照工具切，而不是照工具的功能切分，就不會有概念重複出現的問題，但這就代表圖片又錯了，不該是閉環箭頭，因為一個工具學完就沒了，你不會再回去看 Tutorial，而且 How-to 的箭頭應該要新增一個指向自身的，表示工具有多個功能，對應多份 How-to。

一點批判

前一段還能說是沒想清楚、筆誤之類的，畢竟這又不是論文，本來就不該拿高規格去審視（實際上這也沒有很高規格，這個架構這麼多人用，是不是推薦要照順序本來就該講清楚，一個介紹文檔怎麼寫的文檔介紹自己都講的不清不楚，那不是很荒謬嗎），但是它的象限圖就真的很有問題了。

我完全不同意 Diátaxis 的座標軸定義，y 軸還好說，實作和理解，而 x 軸的 acquisition（serve our study 獲取知識、學習）對應 application （serve our work 應用、工作）就超怪，為啥工作和學習是互斥的？？？這不是相輔相成的東西嗎？？？你都學不會了，application 上去的極大可能也會出錯。

正常來說，分類矩陣上下之間、左右之間都是互斥的東西，比如艾森豪矩陣、波士頓矩陣、SWOT 分析、安索夫矩陣，他們都是 x 軸左右互斥，y 軸上下互斥，然而 Diátaxis 是耦合的，Diátaxis 自己的描述也寫 distinct but bound up with each other，根本是把分類矩陣根本亂用一通。

你應該要知道 Diátaxis 是哪來的，它是從業者長期歸納的心得，不是正經的研究理論。比如說為什麼 Diátaxis 有效，文檔開了一個玩笑說「Diátaxis 有效，因為它 work」，並且說這種講法顯然站不住腳，讀完這個開場白我還以為後面要正式說明為什麼有效，然而後面講了服務用戶、滿足需求、分類表格，前面兩個是廢話，後面一個是沒有解釋原因的自創，還是沒提到為什麼有效。

這樣你應該能感受到 Diátaxis 架構不是「理論」只是「心得」而已，沒有說它測試了哪些不同的文檔組織方式測試得到了什麼效果，沒有真實的反饋記錄，也沒有什麼心理學的什麼理論支持，甚至連它經歷了哪些過程，哪些方法好，哪些方法不好，幾經測試最終得出了 Diátaxis 架構的結論，這些全部都沒有，只是說「了解使用者的需求」、「自行定義象限」、「自行幫四個區域填上內容」，沒有原因，因為這只是從業者長期歸納的心得。

我的 Diátaxis

不過我也沒有完全否定 Diátaxis，雖然不同意座標軸，但是我同意四個層面的分類，這對技術寫作的好處在於知道自己在寫哪一部分，並且每個部分的用字遣辭就要是那個部分的樣子。

我對四個層面的寫法也和 Diátaxis 官方的不一樣：

Tutorial: 超簡單，用戶不該感到任何挫折，你幫他排除所有情況，在路上的所有問題都幫他解釋好，但是這是最小的解釋，能動等級的解釋，真正的解釋會放在後面，不會有任何需要讀者動腦的地方，Tutorial 只用於建立信心。
Explanation: 我不會放在最後，我會和 How-to 放在一起，事實上你永遠解釋不完，東西太多了，軟體也會變，你不可能所有東西都解釋一遍，只該講最重要的地方。
How-to: 解決某一個特定問題的方法，這些問題必須是常見問題，或者不是那麼直觀需要多個功能合併才能組裝出來。
Reference: 最簡化的參考文件，所有項目使用最少的文字描述，預設讀者對整個系統都有一定程度以上的了解，而不是在裡面放一堆介紹，並且盡可能避免使用範例。

我自己會偏好這樣：Tutorial 一樣在開頭沒有錯，用戶可以快速建立信心，再來是 Explanation + How-to，這兩個不該分開介紹，而且這裡的 Explanation 是更簡化、更大方向的，因為他和 How-to 合併在一起了。隨著連續幾輪的 Explanation + How-to 結合介紹各種功能的使用，最後會有一個大表作為 Reference 收尾。

隨著軟體特性、目標用戶的特性不同，就可以修改 Explanation/How-to 的佔比或拆分回原版結構，並且適當引入 loop。