我不完全贊同 Diátaxis 架構

Diátaxis 最近受到很大的推崇，尤其是被開源專案大量參考，但是隨著功課做了越來越多就越不贊同 Diátaxis 架構，包含順序問題和座標軸問題。

先對齊用語後續文章閱讀更順，本文的象限指 Tutorial/How-to 這種文檔分類，座標軸指 Action/Cognition 這種文檔分類方式，就和你平常認知的象限和座標軸一樣。

順序問題

Diátaxis 雖然沒有直接說出四個象限就必須照它建議的順序編排文檔，但是 Diátaxis 自己的文字說明、編排和單向迴圈的圖示，實際上就是在明示應該照順序編排。

The journey around the map 這段雖然沒有直接說「就應該照順序編排文檔」，但是整段都在講順序，圖也畫了順序。如果 Diátaxis 根本就不推薦照順序排，自然不用說讀者不見得會照順序讀，因為寫手編排的文檔本身就不存在順序，讀者連要照順序閱讀的可能性都沒有；同理，如果不推薦，也不用說照順序最符合人類學習歷程，也不會連圖都畫單向迴圈的箭頭順序。反過來講，只有 Diátaxis 建議照順序編排文檔，The journey around the map 這個段落才符合邏輯。

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

錯誤的座標軸

順序還能說是理念不同，但是 Diátaxis 的象限圖就真的很有問題了。

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

Diátaxis 其實知道自己的座標軸不互斥，甚至自己都說座標軸非常耦合（distinct but bound up with each other），然而真正有問題的不是座標軸耦合，是用耦合的座標軸來分類文檔。

正常來說，分析矩陣上下之間、左右之間都是互斥的東西，比如艾森豪矩陣、波士頓矩陣、SWOT 分析、安索夫矩陣，他們都是 x 軸左右互斥，y 軸上下互斥，遇到問題用座標軸一眼就能分類問題，但是 Diátaxis 卻完全做不到一眼分類，這個問題的根本原因正是把耦合的座標軸放到不該耦合的分析矩陣裡面。

這也是為什麼會有 Tutorial 和 How-to 搞混，Reference 和 Explanation 搞混的問題，因為他借了分析矩陣的殼，用了分析矩陣幫四種文檔做表格、分門別類，然而座標軸本身就已經耦合了，那分類時當然會遇到模稜兩可的情況，甚至文檔還得花兩頁特別解釋容易搞混的分類。試試看把座標軸拿開，直接看四種文檔分類的定義，沒有錯誤的座標軸誤導，你會發現豁然開朗，根本就沒有混淆的問題。

座標軸對應的象限不直觀

我們把座標軸沒有根據的問題擺在一旁，也不管座標軸耦合的問題，即使這樣都沒辦法完全排除疑惑，因為分類的「象限內容」又是他自己填進去的，不只沒講理由，填入的內容還很不直觀，在講不直觀帶來的問題之前，我們先看其他分析矩陣的案例。

常見的分析矩陣每個象限填入的東西都非常直覺，比如艾森豪矩陣的 重要 + 緊急 > 重要且緊急，波士頓矩陣的 高成長 + 高佔有 > 明星產品，SWOT 分析的 企業外部 + 有利因素 > 企業的機會，安索夫矩陣的 新產品 + 新市場 > 多角化策略，全部都直觀易懂，想都不用想，能透過座標軸明確清晰的分類問題。

但是 Diátaxis 很不直觀，舉一個簡單的例子，我們根本沒辦法直觀把 獲取知識Acquisition + 行動Action 連結到 Tutorial，象限填入的內容和座標軸根本沒辦法直觀的把他對起來，其他象限也都有同樣問題。

所以座標軸總共有三個問題

1. 座標軸是他自己選的，沒有解釋那麼多種切法為何偏偏選這四個。
2. 兩個座標軸合起來決定的象限內容也是他自己選的，沒有解釋那麼多種東西可以填入為何偏偏選這四個。
3. 座標軸和象限的對應不只不直觀，也仍然沒解釋原因。

我的 Diátaxis

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

我對四個層面的寫法和 Diátaxis 官方的略有不同：

• Tutorial: 超簡單，讀者不該感到任何挫折，作者幫讀者排除所有問題，在路上的所有問題都幫他解釋好，但是這是最小的解釋，能動等級的解釋，真正的解釋會放在後面，不會有任何需要讀者動腦的地方，Tutorial 只用於建立信心。
• Explanation: 我不會放在最後，我會和 How-to 放在一起，並且只講關鍵內容，因為東西太多了永遠解釋不完，軟體也會變，你不可能所有東西都解釋一遍，只該講最重要的地方。
• How-to: 解決某一個特定問題的方法，這些問題必須是常見問題，或者不是那麼直觀需要多個功能合併才能組裝出來。和 Explanation 一起寫的好處是用戶理解概念之後，馬上就能用這個概念解決實際問題，而不是理解了卻不知道怎麼解決，或是知道怎麼解決卻不懂原因。
• Reference: 最簡化的參考文件，包含系統所有內容，也包含所有次要、不值得作為獨立文章寫出來的內容。所有項目使用最少的文字描述，預設讀者對整個系統都有一定程度以上的了解，而不是在裡面放一堆介紹。

Tutorial 一樣在開頭沒有錯，讀者可以快速建立信心，再來是 Explanation + How-to 合併，讓讀者在理解當下就能立刻解決實際問題，且 Explanation 是更簡化、更大方向的，因為他和 How-to 合併在一起了。隨著連續幾輪的 Explanation + How-to 結合，介紹各種功能的使用後，最後會有一個大表作為 Reference 收尾。

隨著軟體特性、目標讀者的特性不同，就可以修改 Explanation/How-to 在文章中的佔比，或拆分回原版四個區塊的結構。

再次論證不合理的座標軸

現在請讀者花五秒鐘思考「我的 Diátaxis」這個段落是否存在明顯的邏輯錯誤。

...

...

...

...

...

如果讀者完全理解、信服 Diátaxis 的座標軸分類，那麼把 How-to 和 Explanation 一起寫的這個論述應該會非常生硬不合邏輯，因為 How-to 和 Explanation 在座標軸中是對角，這樣寫是錯誤中的錯誤，如果讀者接受且理解 Diátaxis 的理論，那應該要立刻發現這個論述是錯的，然而這樣描述看起來卻很符合直覺，要嘛是這段有讀者和筆者都沒想到的邏輯謬誤，要嘛再度證明 Diátaxis 的座標軸不合邏輯，不只上下左右之間互相耦合，連對角之間都耦合。

符合直覺不見得就對，但是如果理論框架要違反直覺，那他至少要講的出原因，然而 Diátaxis 都是毫無原因的 Ipse dixit。

Ipse dixit

Diátaxis 在 Foundations 介紹自己為何有效，看似有介紹但是實際上只是概念說明，這個頁面講的內容如下

1. 開場白
2. Two dimensions of craft 自己定義了座標，沒有原因，沒有說為什麼偏偏是選這種切法，這是斷言 Ipse dixit¹，不是論證
3. Serving needs 用自己定義的座標，自行填入四個象限，還是沒講原因，仍然是斷言，第二層薄弱
4. Serving needs 的表格沒有解釋任何東西
5. 結尾自吹自擂沒有提供資訊

Foundations 裡面寫的全是斷言，完全解釋不了為什麼 Diátaxis 有效。

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

這樣你應該能感受到 Diátaxis 架構不是「理論」只是「心得」而已，沒有說它測試了哪些不同的文檔組織方式得到了什麼效果，沒有真實的反饋記錄，也沒有什麼心理學的什麼理論支持，甚至連它經歷了哪些過程，哪些方法好，哪些方法不好，幾經測試最終得出了 Diátaxis 架構的結論，這些全部都沒有。

小結

既然用了分析矩陣，那就應該和分析矩陣一樣能清晰的分類問題，而不是座標軸耦合，而且四個象限和四個座標軸難以直觀對應。如果 Diátaxis 只有四種文檔分類不使用座標軸，那我完全接受沒有意見，但是在我看來 Diátaxis 更像是先想到分類才去想座標軸硬套上去的，因此才會有本文講的那些問題，去掉座標軸你會發現一切撥雲見日。

至於文檔編排順序則是理念不同，就每個人都可以有自己的編排理念。

對我來說，Diátaxis 的價值是提醒我們不要把不同內容混在一起寫。

相關文章：Diátaxis Documentation

本文的內容基於文檔的 957c09ca 版本。