Skip to main content

新內容歸檔決策樹

任何新文件加入 Internal Wiki 之前,先走完本決策樹。找不到位置 ≠ 開新分類。

決策樹​

我要寫新文件,放哪?
│
├─ 是「給新人從零學的路徑」嗎?
│   └─ YES → onboarding/learning-tracks/
│
├─ 是「特定 library / framework 的使用指南」?
│   └─ YES → framework/{對應子分組}/
│            (若無對應子分組,先評估該開新分組還是合進 core)
│
├─ 是「設備或系統間的通訊協定」?
│   └─ YES → protocols/{協定名}/
│
├─ 是「資料儲存 / 部署 / 運維 / 觀測」?
│   └─ YES → infrastructure/{data-storage|deployment|observability}/
│
├─ 是「團隊工作流程 / SOP」?
│   ├─ 自動化 Pipeline 相關 → pipeline/
│   └─ 手動 / 概念 → workflow/
│
├─ 是「重大架構決策」?
│   └─ YES → architecture/adr/ADR-NNN-*.md (用 template)
│
├─ 是「踩坑紀錄 / 後驗教訓」?
│   └─ YES → architecture/pitfalls/
│
├─ 是「Legacy 系統遷移指南」?
│   └─ YES → architecture/migration/
│
├─ 是「跨專案重用的架構 Pattern(≥ 2 個專案實作過)」?
│   └─ YES → architecture/patterns/
│
├─ 是「合規驗證策略 / 撰寫規範」?
│   └─ YES → standards/{compliance|wiki|mermaid-templates}/
│
└─ 都不是?
    └─ 不要新增第一層分類。先到 wiki-architecture.md 提案討論。
       第一層分類超過 12 個觸發強制重組。

細節對照​

Onboarding vs Framework vs Architecture​

我寫的是...放哪範例
「新人第一週要學的東西」onboarding/learning-tracks/C# / Spec Kit / Beckhoff Learning Track
「某個 library 怎麼用」framework/{subgroup}/Polly 韌性策略
「為什麼選這個 library / 架構」architecture/adr/ADR-002 Beckhoff 評估
「跨 library 反覆出現的設計法」architecture/patterns/PC+PLC 雙層架構

Protocols vs Framework​

重點是...放哪
協定本身的規格、訊息格式protocols/{protocol}/
.NET SDK 怎麼包這個協定framework/{subgroup}/{lib}/
兩者都要兩邊都寫,互相連結

例如:

  • Modbus 協定規格 → protocols/modbus-integration-guide.md
  • FluentModbus library 使用 → framework/{適合子分組}/fluent-modbus/(如有)

Infrastructure vs Workflow​

我寫的是...放哪
「怎麼部署到 Cloudflare Pages」(操作)infrastructure/deployment/
「Git 分支策略」(流程)workflow/
「為什麼選 Cloudflare 而非 AWS」(決策)architecture/adr/

需要建立新子分組時​

不是任意建子分組。觸發條件(必須之一滿足):

  1. 同類文件數 ≥ 4 篇,且預期還會增加
  2. 既有文件難以歸入現有子分組
  3. 多個專案會引用同一群文件

建立新子分組時必須:

  • 加 _category_.json(label / position / collapsed)
  • 寫 README.md(收錄 / 不收錄 / 子分組規則)
  • 同步更新上層 README 的「子分組」列表
  • 同步更新 wiki-architecture.md 第 2 節(如果是第一層)

需要建立新第一層分類時(高度限制)​

第一原則:盡量不要。第二原則:強制走治理流程。

觸發條件(必須全部滿足):

  1. 既有 9 個分類無一適合
  2. 預計文件數 ≥ 5 篇,且未來持續成長
  3. 跟既有任一分類「使用者目的」不同
  4. Hubert(或 Lead)同意

執行步驟:

  1. 在 wiki-architecture.md 第 2 節 提案
  2. PR review
  3. 通過後再建立目錄 + 文件

我還是不確定怎麼分​

提交 PR 時放在最接近的位置,並在 PR 描述標明 "IA 不確定",由 Reviewer 判斷。