# 📘 TTR Wiki 撰寫指南

## 一、架構原則

本 Wiki 應採用以下結構設計：

* **書架（Shelf）**：依「部門」分類
* **書本（Book）**：依「實際工作項目」命名
* **章節（Chapter / Page）**：記錄「執行細節與知識」

此設計目的在於：

* 明確對應責任歸屬（誰負責）
* 保持文件可擴展性
* 避免知識分散與重複

---

## 二、書架命名規範（部門）

書架名稱應符合：

* 使用車隊各「部門」命名
* 避免模糊或過於抽象名稱
* 保持長期穩定（不要頻繁更動）

---

## 三、書本命名規範（工作項目）

書本應對應「一個具體任務或系統」，命名需具備：

* 可辨識性（看到名稱就知道在做什麼）
* 可擴展性（未來可以新增內容）
* 避免過大或過小範圍

### ✅ 正確範例

* 電池管理系統(BMS)
* 懸吊系統
* 車身人因工程
* 數據分析
* STM32 嵌入式系統
* 車隊運營
* 專案管理

### ❌ 錯誤範例

* STM cube IDE 教學 (範圍過小)
* 電路（範圍過大）
* 雜項（不可用）

---

## 四、章節撰寫標準（最重要）

每個書本內頁應遵循「工程文件結構」：

### 建議基本結構

```markdown
# 1. Overview（概述）
- 目的
- 功能
- 系統位置

# 2. System Architecture（系統架構）
- 架構圖
- 模組說明

# 3. Design（設計）
- 設計理念
- 選型原因

# 4. Implementation（實作）
- 程式 / 電路 / 機構
- 關鍵參數

# 5. Testing（測試）
- 測試方法
- 測試結果

# 6. Debug / Issue（問題紀錄）
- 遇到的問題
- 解法

# 7. Reference（參考資料）
```

---

## 五、撰寫原則

### 1️⃣ 可交接性（最重要）

文件應讓「新成員能直接接手工作」

---

### 2️⃣ 工程導向（避免流水帳）

❌ 不要寫：

* 今天做了什麼

✅ 應該寫：

* 為什麼這樣設計
* 遇到什麼問題
* 如何解決

---

### 3️⃣ 一致性

* 標題格式統一（使用 Markdown）
* 命名規則一致
* 單位（V / A / mm）統一

---

### 4️⃣ 可搜尋性

* 使用關鍵字（如 CAN、BMS、PID）
* 避免模糊描述

---

## 六、版本與維護

* 每次重要修改需更新內容
* 避免刪除舊資料（可標註 deprecated）
* Debug 與 Failure Case 必須保留

---

## 七、禁止事項

* ❌ 不可建立「雜項」、「其他」類型書本
* ❌ 不可僅貼程式碼無說明
* ❌ 不可只放圖片無解釋
* ❌ 不可寫無法理解的個人筆記

---

## 八、目標

本 Wiki 的最終目標為：

> 建立車隊的「工程知識資產系統」，使技術能被累積、傳承與複製。