Skip to main content

📘 TTR Wiki 撰寫指南

一、架構原則

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

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

此設計目的在於：

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

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

書架名稱應符合：

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

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

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

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

✅ 正確範例

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

❌ 錯誤範例

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

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

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

建議基本結構

# 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 的最終目標為：

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

Back to top