Skip to main content

Wiki 架構治理規則 Wiki Architecture Governance

本文件定義 GatherTech Internal Wiki 的資訊架構（IA）設計原則、量化指標、擴展規則。所有對 Wiki 結構的變更都必須遵守本文件。

1. IA 設計哲學​

兩根支柱:

支柱解決什麼
第一層分類穩定結構不會因為新技術加入而被迫重組
明文治理規則任何新內容都有判斷依據放哪

第一層用「使用者目的」分類(穩定),第二層用「技術主題」分類(可演進),第三層才是文件本身。

2. 第一層分類定義(9 個,理想 7-10)​

位置分類slug收錄
1新人入門onboarding/Onboarding、學習路徑、開發環境
2GST Frameworkframework/.NET library 使用指南、Pattern
3通訊協定protocols/設備/系統通訊協定整合
4基礎建設與部署infrastructure/DB、儲存、部署、運維
5工作流程workflow/Git、Spec Kit、Skills
6Pipeline 自動化pipeline/Multi-Agent Pipeline
7RPA 自動化引擎rpa/GST RPA 引擎
8架構決策與經驗architecture/ADR、踩坑、遷移、Pattern
9規範與合規standards/合規驗證、Wiki 規範、Mermaid

任何新增第一層分類必須先在本文件討論並更新此表。

3. 量化指標(防止失控)​

規則觸發條件動作
第一層上限超過 12 個強制重組,不准加新分類
第一層理想數7-10 個設計目標
子分組門檻一分類項數 > 10必須加子分組
子分組過深第三層子分組 > 6觸發再分組
孤兒清理一分類 < 3 項 持續 6 個月評估合併
預留位置存活期README.md only 持續 12 個月移除預留
README 必填每個第一層 + 子分組沒寫不准進主線

4. 每個第一層分類必須有的 README​

格式必填三段:

# {分類名}

## 收錄什麼 (What)
{清楚定義:哪種文件該放這裡}

## 不收錄什麼 (What NOT)
{明確排除:容易誤放的東西去哪}

## 子分組規則
{若超過 10 項該如何分組}

Why: 不寫 README,半年後沒人記得分類定義,內容會誤放。

5. Diátaxis 文件類型 metadata​

新文件強制 frontmatter 包含 doc_type + audience + last_reviewed。舊文件不強制補。

doc_type(Diátaxis 框架)​

類型目的範例
tutorial學習導向(新人 step-by-step)onboarding 課程、Polly Quickstart
how-to任務導向(如何做某事)「如何設定 ADS 連線」
reference資訊導向(API / 設定查找)Polly Strategy 列表、命名規範
explanation理解導向(背景 / 原理 / 決策)ADR、Pattern 說明、合規策略

audience​

受眾對象
newcomer第一週的新人
developer一般開發者
architect架構師 / Lead
ops運維 / 部署
qa測試 / 驗收
maintainer文件維護者(本身)

Frontmatter 範例​

---
title: Polly 韌性策略
sidebar_position: 1
doc_type: reference
audience: developer
last_reviewed: 2026-05-07
---

6. 命名規範​

種類規則範例
第一層目錄全小寫、橫線連字符infrastructure/、pipeline/
子分組目錄全小寫、橫線連字符data-storage/、industrial-control/
ADR 檔案ADR-NNN-{kebab-case}.mdADR-001-FileStorage-Layer-Design.md
Pattern 檔案{kebab-case}.mdpc-plc-dual-layer.md
一般文件{kebab-case}.mdpipeline-overview.md
READMEREADME.md(每分類必有)—
Category config_category_.json(必有)—

7. 變更審查 Checklist​

任何 Wiki 變更 PR 必須通過:

  • 新文件有 doc_type + audience + last_reviewed frontmatter
  • 新文件路徑符合決策樹(見 new-content-decision-tree)
  • 修改既有結構時,本文件已同步更新
  • 沒有破壞跨檔引用(build 沒有 broken link)
  • 第一層分類數仍 ≤ 12
  • 任何 > 10 項的分類已加子分組

8. 例外處理​

當決策樹無法分類時,不要直接新增第一層分類。先到本文件討論並更新規則。

緊急例外處理流程:

  1. 在 PR 內同步更新本文件第 2、3 節
  2. 標註「IA 變更」標籤,需要 Hubert(或未來 Lead)review
  3. Merge 後通知所有 Agent 重新讀取 wiki

相關​