メインコンテンツまでスキップ

Wiki 撰寫規範

本頁定義 Internal Wiki 的頁面格式、交叉引用規則與知識 Ingest 流程。

語言規範​

  • 內文使用繁體中文（台灣用語）
  • 技術名詞保留英文（例如：Modbus、SignalR、GAMP5）
  • 程式碼區塊內容保持原始語言，不翻譯

頁面模板​

每篇頁面必須包含以下 frontmatter：

---
title: 頁面標題
description: 一句話描述本頁內容（供搜尋與 Agent 摘要使用）
sidebar_position: 1
tags:
  - 相關標籤
---

必要欄位​

欄位說明必填
title頁面標題是
description一句話摘要是
sidebar_position側邊欄排序是
tags分類標籤建議

頁面結構建議​

# 標題（與 frontmatter title 一致）

一段簡短摘要，說明本頁涵蓋什麼。

---

## 背景 / 為什麼需要這個

## 核心內容

## 範例 / 實作步驟

## 注意事項

## 相關文件

交叉引用格式​

使用標準 Markdown 相對連結：

<!-- 同分類內引用 -->
[框架指南](../framework/framework-guide)

<!-- 跨分類引用 -->
[Git 工作流程](../workflow/git-workflow-guide)

<!-- 引用特定章節 -->
[部署流程 - 環境設定](../deployment/velopack-deployment-guide#環境設定)

規則：

  • 使用相對路徑，不使用絕對 URL
  • 連結文字應有意義，避免「點這裡」
  • 引用外部資源時標注 (外部) 標記

Ingest 流程​

新知識加入 Wiki 的標準流程：

1. 提議（Propose）​

  • 在對應分類下建立新頁面，遵循頁面模板
  • 頁面標題以 [草稿] 前綴標示（完成後移除）
  • Commit message 格式：docs(internal): add draft - <頁面標題>

2. 撰寫（Write）​

  • 依照頁面模板填寫所有必要欄位
  • 加入交叉引用連結
  • 確保程式碼範例可執行或標注為虛擬碼

3. 審查（Review）​

  • 透過 Pull Request 提交
  • 至少一位團隊成員 review
  • 確認：語言規範、模板完整性、連結有效性

4. 發布（Publish）​

  • 移除 [草稿] 前綴
  • 合併至 main 分支
  • 更新 Wiki 首頁（如為新分類的第一篇）

5. 維護（Maintain）​

  • 定期檢查連結有效性
  • 技術內容隨版本更新同步修正
  • 過時內容標注 [已過時] 並說明替代方案