跳至主要内容

ADR-001: docs-web/guides 文檔架構

ADR 編號: 001 狀態: 提議中 (Proposed) 決策日期: 2026-02-01 決策者: Development Team

摘要​

採用 Diátaxis 框架組織 docs-web/guides/ 文檔，明確區分教學、操作指南、概念解釋和參考手冊四種類型。

背景 (Context)​

問題陳述​

docs-web/guides/ 目錄的文檔結構存在以下問題：

  1. 入口重複：README.md、getting-started.md、quickstart/ 三者功能重疊
  2. 內容混合：大多數文檔同時包含概念解釋、操作步驟和 API 參考，讀者難以快速找到需要的資訊
  3. 缺乏明確的組織原則：新增文檔時沒有判斷標準，導致結構逐漸混亂

限制條件​

  • 需與現有 Docusaurus 機制相容
  • 遷移成本需可控（漸進式改善）
  • 需同時服務人類讀者與 AI 助手

目的與對象定義​

目的 (Purpose)​

docs-web/guides/ 的目的是：

協助開發者學習並有效使用 AppFuse Web 框架建構 React 應用程式

具體而言：

  • 讓新手能在 30 分鐘內建立第一個專案
  • 讓開發者能快速找到特定任務的解決方案
  • 提供足夠的背景知識理解設計決策
  • 作為 API 和配置的查詢參考

對象 (Audience)​

對象背景假設主要需求
新手開發者熟悉 React，初次接觸 AppFuse快速上手、建立第一個專案
專案開發者已有 AppFuse 專案經驗解決特定問題、查詢 API
架構評估者評估是否採用 AppFuse理解設計理念與權衡
AI 助手協助開發者完成任務準確的規格與範例

範圍界定​

包含不包含
框架使用指南元件 API 詳細規格（在 components/）
整合與配置說明互動式範例（在 Storybook）
設計理念與決策業務邏輯實作（在參考實作專案）

考量的方案 (Options Considered)​

方案 A: 維持現狀（按功能分類）​

說明: 維持現有結構，僅修正重複與命名問題

優點:

  • ✅ 無遷移成本
  • ✅ 開發者熟悉

缺點:

  • ❌ 無法解決內容混合問題
  • ❌ 新增文檔仍無判斷標準

評分: 2/5

方案 B: Diátaxis 框架​

說明: 採用 Diátaxis 四象限分類：Tutorials、How-to Guides、Explanation、Reference

優點:

  • ✅ 有明確的分類標準，每份文檔有清晰的歸屬
  • ✅ 業界廣泛採用（Django、NumPy、Gatsby）
  • ✅ 符合讀者不同情境的需求

缺點:

  • ❌ 需要遷移現有文檔
  • ❌ 部分文檔需拆分

評分: 4/5

方案 C: 任務導向結構​

說明: 以「我想要...」的任務為主軸組織文檔

優點:

  • ✅ 直觀，符合使用者搜尋習慣
  • ✅ 易於擴展

缺點:

  • ❌ 概念性文檔難以歸類
  • ❌ 任務粒度難以統一

評分: 3/5

決策 (Decision)​

選擇方案: B - Diátaxis 框架

核心理由:

  1. 提供明確的分類標準，避免未來再度混亂
  2. 業界已驗證的方法論，有豐富的參考案例
  3. 四種類型對應四種閱讀情境，讀者能快速定位

Diátaxis 分類定義​

Tutorials（教學）​

屬性定義
導向學習導向 (Learning-oriented)
目的帶領讀者從零完成一個具體目標
讀者狀態「我想學習」
特徵步驟式、有明確起點與終點、結果可重現
範例「建立第一個 Applet」、「建立新專案」

判斷標準：

  • ✅ 有明確的學習目標
  • ✅ 讀者跟著做會得到具體成果
  • ✅ 假設讀者沒有相關經驗

How-to Guides（操作指南）​

屬性定義
導向任務導向 (Task-oriented)
目的解決特定問題或完成特定任務
讀者狀態「我想完成 X」
特徵直接給出解決方案、假設讀者有基礎知識
範例「如何實作表單驗證」、「如何切換 Mock 到真實 API」

判斷標準：

  • ✅ 標題通常是「如何...」或動詞開頭
  • ✅ 假設讀者已了解基礎概念
  • ✅ 專注於解決單一問題

Explanation（概念解釋）​

屬性定義
導向理解導向 (Understanding-oriented)
目的解釋為什麼這樣設計、提供背景脈絡
讀者狀態「我想理解為什麼」
特徵討論式、提供多角度觀點、說明權衡
範例「Applet 設計模式」、「狀態管理策略」

判斷標準：

  • ✅ 回答「為什麼」而非「怎麼做」
  • ✅ 提供設計決策的背景與理由
  • ✅ 可以獨立閱讀，不需跟著操作

Reference（參考手冊）​

屬性定義
導向資訊導向 (Information-oriented)
目的提供準確、完整、可查詢的規格資訊
讀者狀態「我需要查 X 的規格」
特徵乾燥、結構化、完整性優先
範例「工具函數 API」、「專案結構說明」、「路由配置規格」

判斷標準：

  • ✅ 描述性質（是什麼）而非指導性質（怎麼做）
  • ✅ 適合快速查閱，不需從頭讀到尾
  • ✅ 強調準確性與完整性

目標結構​

docs-web/guides/
├── README.md                      # 導覽頁
│
├── tutorials/                     # 🎓 教學
│   ├── _category_.json
│   ├── create-project.md
│   ├── first-applet.md
│   └── first-form.md
│
├── how-to/                        # 🔧 操作指南
│   ├── _category_.json
│   ├── form-validation.md
│   ├── handle-api-errors.md
│   ├── switch-mock-to-real.md
│   ├── add-language.md
│   ├── customize-theme.md
│   └── add-route-guard.md
│
├── concepts/                      # 💡 概念解釋
│   ├── _category_.json
│   ├── applet-pattern.md
│   ├── state-management.md
│   ├── mock-api-strategy.md
│   └── form-architecture.md
│
└── reference/                     # 📖 參考手冊
    ├── _category_.json
    ├── project-structure.md
    ├── routing.md
    ├── i18n.md
    ├── messaging.md
    ├── theming.md
    ├── utils.md
    └── testing.md

實作指南 (Implementation Guidelines)​

新增文檔時的判斷流程​

這份文檔的主要目的是什麼？
│
├─ 帶讀者從零學會某件事 → tutorials/
├─ 解決特定問題 → how-to/
├─ 解釋為什麼這樣設計 → concepts/
└─ 提供規格資訊供查詢 → reference/

必須遵守的規則​

  1. 單一職責：一份文檔只屬於一個分類，不混合多種類型
  2. 命名一致：
    • tutorials: 動詞 + 名詞（如 create-project.md）
    • how-to: 動詞 + 任務（如 handle-api-errors.md）
    • concepts: 名詞 + 概念（如 applet-pattern.md）
    • reference: 名詞（如 routing.md）
  3. 交叉引用：在文檔中適當連結相關的其他類型文檔

檢查清單​

新增文檔時：

  • 確認文檔屬於哪個分類
  • 確認標題符合該分類的命名慣例
  • 確認 sidebar_position 不與同目錄其他文檔重複
  • 如需引用其他類型內容，使用連結而非複製

相關文檔 (References)​

外部資源​

相關 ADR​

  • （待建立）ADR-002: docs-web/components 文檔架構

變更歷史 (Change Log)​

日期變更內容變更者
2026-02-01初版草稿Claude

文檔維護者: Development Team + AI Assistant 最後審閱: 2026-02-01