README 工程與技術文件撰寫指南 是做什麼的？
這是一套嚴謹的框架，用於創建世界級、人類可讀的 GitHub 儲存庫 README，它尊重讀者的時間、清晰地傳達技術價值，並完全杜絕泛濫的行銷空話。
1. 核心哲學：30 秒法則
開發者和使用者並不是從頭到尾「閱讀」文件——他們是在高速掃描。請設身處地為一位在凌晨兩點偶然發現你儲存庫的疲憊開發者著想。
你的 README 必須在 30 秒內回答三個問題：
- 這是什麼？ （一句清晰、零行銷術語的定義）。
- 我為什麼要在意？ （它解決了什麼真實世界的問題，以及取代了哪些令人沮喪的替代方案）。
- 我現在要怎麼執行它？ （一個三步驟、可直接複製貼上的快速入門，並附上經過測試的命令）。
2. 清晰、接地氣寫作指南
文件常會不自覺地淪為誇大不實的公關用語。高品質的開源專案應完全避免這種語氣。
2.1 禁用字詞與陳腔濫調對照表
| ❌ 禁用流行語 / 陳腔濫調 | ✔️ 清晰、接地氣的替代寫法 |
|---|---|
| 「在當今快節奏的數位環境中...」 | （直接刪除。直接切入問題核心）。 |
| 「輕鬆傳輸 / 無縫整合...」 | 「從瀏覽器拖放檔案，它們就會出現在你的手機上。」 |
| 「一個革命性、尖端平台...」 | 「一個輕量級、自託管的個人轉發器。」 |
| 「將你的生產力提升到全新高度...」 | 「讓你不再需要把連結用 Email 寄給自己。」 |
| 「現代開發的見證...」 | （刪除。像個工程師說話，而不是公關公司）。 |
| 「完全消除了巨大的英雄橫幅...」 | （永遠不要吹噓內部的重構。直接陳述 UI 現在提供了什麼）。 |
| 「防禦性網頁登入架構...」 | 「使用 HttpOnly SameSite Cookie 和 CSRF 令牌的安全登入。」 |
| 「零骨架 SWR 快取...」 | 「即時載入：打開你的收件匣時不會出現空白畫面。」 |
2.2 真誠寫作規則
- 「週二咖啡」測試： 大聲讀出你的草稿。聽起來像是一位體貼的軟體工程師在喝咖啡時向同事介紹他最愛的工具嗎？如果聽起來像公司的行銷宣傳手冊，那就重寫。
- 徽章紀律： 將徽章限制在 3 到 6 個有意義的指標（版本號、建置/CI 狀態、授權條款、核心技術棧）。不要堆疊 15 個裝飾性徽章，這只會分散對專案的注意力。
- 無神祕的前置需求： 永遠不要直接寫
docker compose up或npm start而不列出前置需求以及環境憑證從何取得。
3. 雙受眾結構
優秀的文件能橋接兩種截然不同的受眾，而不犧牲清晰度：
flowchart TD
Audience["儲存庫訪客"]
Audience --> HomeUser["1. 一般使用者 / 日常用戶<br>（想知道此專案能否解決他們的痛點）"]
Audience --> Sysadmin["2. 工程師 / 系統管理員 / 開發者<br>（想了解架構、安全性和技術棧）"]
HomeUser --> PlainSection["「為什麼存在？」 章節<br>- 真實情境（不再需要傳送簡訊機器人或 Email 附件）<br>- 三步驟概念工作流程<br>- 隱私與自託管優勢"]
Sysadmin --> TechSection["「運作原理」 章節<br>- 架構圖（Mermaid）<br>- 元件職責<br>- 安全性與令牌模型<br>- 儲存與資料庫機制"]
3.1 為一般使用者設計的白話文
從有共鳴的真實痛點開始：
「你是否曾經為了在手機上複製一段文字，而需要把連結用 Email 寄給自己、在 Telegram 或 WhatsApp 上傳訊息給機器人，或是為了移動一個 PDF 而等待雲端硬碟同步？Vault 用你的私人收件箱取代了這些繁瑣的替代方案。」
3.2 為開發者設計的實質技術深度
接著提供精確的架構與實作細節：
- API 引擎： ASP.NET Core 10 Minimal APIs，直接將最大 100 MB 的檔案串流到磁碟，並進行即時 SHA-256 驗證（零記憶體膨脹）。
- Web SPA： React 19 + TypeScript，使用 SameSite HttpOnly Cookie、CSRF 令牌和鍵盤快捷鍵（
/搜尋）。 - 行動用戶端： 原生 Kotlin Jetpack Compose，具備 WorkManager 離線發送佇列和 Android
FileProvider整合。 - 資料庫： PostgreSQL 18，儲存中繼資料和 14 天滑動會話令牌。
4. 視覺化展示與 UI 佈局
如果你的應用程式有視覺介面（Web、行動裝置或 CLI 輸出），請在開場介紹後立即展示。
4.1 響應式展示表格範例
<table align="center" width="100%">
<tr>
<th width="33%" align="center">📱 行動裝置收件匣</th>
<th width="33%" align="center">⚙️ 裝置管理中心</th>
<th width="34%" align="center">🔐 無縫配對</th>
</tr>
<tr>
<td align="center" valign="top">
<img src="docs/assets/mobile-inbox.png" alt="行動裝置收件匣" width="260px" />
<br/>
<sub><i>即時本地快取、即時搜尋與一鍵操作。</i></sub>
</td>
<!-- 其餘欄位 -->
</tr>
</table>
4.2 截圖規則：
- 資訊型標題： 使用標題描述使用者在該檢視中可以做些什麼，而不是串聯流行語。
- 真實截圖： 始終使用產品實際 UI 的清晰畫面，而非帶有假筆電邊框的通用模型模板。
5. 無懈可擊的快速入門設計
快速入門必須可重現且無需故障排除。
標準三步驟設定：
### 1. 生成本地憑證與認證資訊
```bash
./scripts/setup-local.sh # 或 ./scripts/setup-local.ps1
功能說明：在 .local/tls/ 目錄下生成受信任的 localhost TLS 憑證，並將隨機的引導密碼寫入 .env 檔案。
2. 啟動服務棧
docker compose up -d
3. 開啟你的工作空間
在瀏覽器中導航至 **https://localhost:8080**：
- 使用者名稱：
[email protected]（或owner） - 密碼： 你的
.env檔案中的引導密碼
---
## 6. 標準 README 結構檢查清單
在為任何技術儲存庫撰寫 README 時，請使用此檢查清單：
- [ ] **1. 標頭與標題：** 標誌 / 圖示、標題和一句話功能標語。
- [ ] **2. 重點徽章：** 版本號、建置狀態、核心平台、授權條款。
- [ ] **3. 為何存在：** 用白話文說明日常問題、解決方案以及三步驟工作流程。
- [ ] **4. 視覺導覽：** 包含 Web、行動裝置或 CLI 介面的截圖，並附上實用標題。
- [ ] **5. 核心功能：** 以使用者為中心，按實際任務組織的功能列表。
- [ ] **6. 運作原理（技術面）：** Mermaid 架構圖 + 精簡的元件分解（API、客戶端、資料庫、認證/安全性）。
- [ ] **7. 快速入門（Docker / 本地）：** 前置需求、逐步命令和憑證位置。
- [ ] **8. 行動裝置 / 客戶端設定（如適用）：** 直接下載連結、配對說明和區域網路測試指南。
- [ ] **9. 自動化測試與驗證：** 用於在本地執行後端和前端測試套件的命令。
- [ ] **10. 儲存庫地圖與貢獻：** 清晰的 ASCII 目錄樹、貢獻指南連結以及 MIT / Apache 授權條款。
---
## 7. 參考開源儲存庫
請檢視這些廣受好評的開源 README，以獲取結構和視覺上的靈感：
- **`matiassingers/awesome-readme`**：GitHub 上頂尖 README 的策展目錄。
- **`othneildrew/Best-README-Template`**：業界黃金標準，提供模組化、高影響力的儲存庫模板。
- **`charmbracelet/bubbletea` 與 `charmbracelet/gum`**：卓越的終端機展示、GIF 使用技巧和易於掃描的程式碼區塊。
- **`supabase/supabase`**：極佳的雙受眾平衡，附有清晰的系統架構圖和快速的入門引導。
- **`fastapi/fastapi`**：零摩擦快速入門、真實程式碼範例和清晰價值主張的教科書級別範例。