Skip to main content

Promotion SOP — Personal-Learning ↔ Internal Wiki

定義個人學習成果如何流入公司知識庫,以及反向 demote 規則。

三階段 Promotion Model​

[Stage 1] D:\WorkSpace\GatherTech\Personal-Learning\        ← 個人學習空間
     │
     │  Trigger 任一達成才 promote:
     │   1. 學完一輪官方教材 + 跑完範例
     │   2. 至少 1 個 prototype 跑通
     │   3. 整理成「給別人看的版本」
     │
     ▼
[Stage 2] gathertech-docs/internal/                          ← 公司知識庫(內部)
     │  位置依內容性質:
     │   • 決策依據     → architecture/adr/ADR-NNN-*.md
     │   • 學習路徑     → onboarding/learning-tracks/0X-{topic}/
     │   • 技術參考     → framework/{subgroup}/ or protocols/{protocol}/
     │   • 踩雷紀錄     → architecture/pitfalls/{topic}.md
     │
     │  Trigger:累積 2-3 個案子驗證 + 對外簡報過
     │
     ▼
[Stage 3] gathertech-docs/clients/ or 對外公開站              ← Capability Asset
        Customer-facing capability handbook
        Sales / Strategist 引用素材

Stage 1 → Stage 2:Promote 路徑(按內容性質)​

A. 決策性內容(why we chose X)​

→ internal/architecture/adr/ADR-NNN-{title}.md

格式:Context / Decision / Consequences

範例:ADR-002-Beckhoff-TwinCAT-Evaluation.md

B. 學習路徑(structured curriculum)​

→ internal/onboarding/learning-tracks/0X-{topic}/

包含:

  • overview.md — 路線圖、時間估計、前置條件
  • 01-foundations.md — 第一階段
  • 02-...md — 後續階段
  • pitfalls.md — 踩坑紀錄(同步到 architecture/pitfalls/)
  • cheatsheet.md — 速查表

範例(規劃中):

  • 01-csharp-net-stack/
  • 02-spec-kit-workflow/
  • 03-beckhoff-twincat/(等學成 promote)
  • 04-fda-compliance/
  • 05-industrial-control/

C. 技術參考(library / SDK / protocol 使用)​

→ internal/framework/{subgroup}/{lib}/ 或 internal/protocols/{protocol}/

格式:overview + 子文件

判斷:

  • 是 .NET library SDK → framework/
  • 是通訊協定本身 → protocols/

D. 踩雷紀錄​

→ internal/architecture/pitfalls/{topic}.md 或合併到 common-pitfalls.md

判斷:

  • 內容 > 1 章節 → 獨立檔案
  • 1-2 段 → 合併到 common-pitfalls.md

Stage 1 → Stage 2:Promote Checklist​

從 Personal-Learning 搬內容到 internal 前,確認:

  • 文件有「給別人看」的格式(不是個人 memo)
  • 移除個人化的判斷 / 心情 / 半成品
  • 加上 frontmatter(doc_type / audience / last_reviewed)
  • 落點符合 新內容決策樹
  • 連結互通(連回 ADR / learning-track)
  • Personal-Learning 留 raw 版,不要刪(未來 demote 用)

反向 Demote(Internal → Personal)​

當 internal 文件變成「過時的個人偏好」時:

  • 確認 < 3 個專案使用
  • 至少 6 個月沒更新
  • 沒被其他 wiki 引用
  • 移到 Personal-Learning archive
  • 加 redirect(client-redirects plugin)避免外部斷鏈

Stage 2 → Stage 3:Capability Asset(對外)​

gathertech-docs/clients/ 或新建 customer-facing 內容,只有:

  • 已 production 驗證
  • 至少 2 個客戶案例引用
  • 經 Sales / Strategist 評估有商業價值

才 promote。多數內容應停留在 Stage 2。

範例:Beckhoff 學習成果 Promote 路徑​

預估時程:6-12 個月學成後

階段位置觸發
學習中Personal-Learning/01-Beckhoff-TwinCAT/起步
決策成熟internal/architecture/adr/ADR-002-Beckhoff-TwinCAT-Evaluation.md已寫
第一個 prototype 跑通internal/onboarding/learning-tracks/03-beckhoff-twincat/6-9 個月
第一個 production 案上線internal/framework/industrial-control/twincat-ads.md 等9-12 個月
第一個 Pattern 重用 ≥ 2 案internal/architecture/patterns/pc-plc-dual-layer.md12+ 個月
客戶交付clients/{client}/{project}/隨案發生

觸發點對照表​

從到觸發
Personal-Learningarchitecture/adr決策成熟、有具體理由
Personal-Learninglearning-tracksprototype 跑通
Personal-Learningframework / protocolsproduction 上線
Personal-Learningarchitecture/pitfalls踩雷已驗證為通病
internalclients(對外)商業價值評估通過