文件是技術產品的重要組成部分，撰寫各類技術文件應成為研發人員的日常工作之一。對於個人而言，書寫文件不僅有助於提高寫作水平，還能在寫作過程中重新梳理產品架構，查缺補漏。對於團隊來說，文件有助於知識共享和傳遞，提高開發與協作效率，保證專案後期的可維護性。文件是產品與使用者之間的橋樑，是使用者瞭解、學習和使用產品的關鍵媒介，有助於提升產品力和使用者信心。建議研發人員在產品研發過程中，重視文件的積累和輸出，以保證產品的長期、健康和可持續發展。
本指南僅包含約束技術文件的基本要求，以儘可能地確保文件語言和風格的一致性。
一、基本要求
1. 內容
語言表達清晰流暢，內容全面且成體系。
2. 格式
建議原始文件用 Markdown 格式書寫並存檔，使文件不依賴特定展示平臺，便於傳播及分享。
3. 存放位置
建議儲存在專案 doc 資料夾下。
4. 組成部分
一個技術專案至少包含 README.md 檔案、兩類必要文件和兩類可選文件。
（1）README.md：用於專案簡介及各類文件的入口說明。
（2）專案文件：用於記錄專案執行過程中相關資料，如專案計劃、會議紀要等。
（3）技術手冊：提供詳細的技術資訊，如技術選型、設計方案、使用規範、測試報告、部署配置等文件，既能規範開發過程、支援團隊協作，也能幫助使用者更好地理解和使用產品。
（4）使用者手冊：如果該專案是面向非專業的普通使用者，應向使用者介紹產品及其使用方法，以幫助使用者快速瞭解產品功能並掌握使用方法。
（5）介面文件：如果該專案是後端服務，應包含介面文件，用於維護對外介面說明，以便於團隊內部溝通和跨團隊合作，建議將其儲存到類似 YAPI 的專用介面文件管理平臺，該平臺支援專案管理、線上呼叫、Mock 等必要功能。
整體組成如下：
├── doc
│ ├── 專案文件：[必要]
│ ├── 技術手冊：[必要]
│ ├── 使用者手冊：[可選]
│ ├── 介面文件：[可選]
├── README.md：[必要]
5. 文件體系
（1）專案文件
├── 需求管理：純技術專案，如果使用 gitlab 管理原始碼，可以將需求維護到 issue 上
├── 專案計劃
│ ├── 周
│ ├── 月
│ ├── 季
│ ├── 年
├── 會議紀要
├── 等
（2）技術手冊
├── 技術選型
├── 設計方案
├── 使用規範
├── 部署配置
├── 測試報告
├── 問題定位
（3）使用者手冊
可參考如下文件體系結構：
├── 簡介（Introduction）：[必要] 提供對產品和文件本身的總體的、扼要的說明
├── 快速上手（Getting Started）：[可選] 如何最快速地使用產品
├── 入門篇（Basics）：[必要] 又稱“使用篇”，提供初級的使用教程
│ ├── 環境準備（Prerequisite）：[必要] 軟體使用需要滿足的前置條件
│ ├── 安裝（Installation）：[可選] 軟體的安裝方法
│ ├── 設定（Configuration）：[必要] 軟體的設定
├── 進階篇（Advanced)：[可選] 又稱“開發篇”，提供中高階的開發教程
├── API（Reference）：[可選] 軟體 API 的逐一介紹
├── FAQ：[可選] 常見問題解答
參考自 阮一峰 - 中文技術文件的寫作規範 - 文件體系篇
借鑑案例：YApi
二、書寫規範
以下內容主要參考自 阮一峰 - 中文技術文件的寫作規範
1. 標題
建議最多隻支援四級標題：
（1）一級標題：文章的標題，建議有且僅有一個
（2）二級標題：文章主要部分的大標題
（3 三級標題：二級標題下面一級的小標題
（4）四級標題：三級標題下面某一方面的小標題，謹慎使用四級標題，儘量避免出現，保持層級的簡單，防止出現過於複雜的章節
示例：
# 文件名稱
## 一、二級標題
### 1. 三級小標題
（1）序號1
（2）序號2
### 2. 三級小標題
## 二、二級標題
2. 文字
建議：
（1）避免使用長句。
（2）儘量使用簡單句和並列句，避免使用複合句。
（3）同樣一個意思，儘量使用肯定句表達，不使用否定句表達。
（4）避免使用雙重否定句。
（5）儘量不使用被動語態，改為使用主動語態。
更多文字書寫建議，請查閱 阮一峰 - 中文技術文件的寫作規範 - 文字篇
3. 段落
建議：
（1）一個段落只能有一個主題，或一箇中心句子。
（2）段落的中心句子放在段首，對全段內容進行概述。後面陳述的句子為中心句子服務。
（3）段落之間使用一個空行隔開。
（4）段落開頭不要留出空白字元。
4. 數值
建議：
（1）阿拉伯數字一律使用半形形式，不得使用全形形式。
（2）數值為千位以上，應新增千分號（半形逗號）。
5. 標點符號
建議：
（1）中文語句的標點符號，均應該採取全形符號，這樣可以與全形文字保持視覺的一致。
（2）如果整句為英文，則該句使用英文/半形標點。
（3）句號、問號、歎號、逗號、頓號、分號和冒號不得出現在一行之首。
（4）點號（句號、逗號、頓號、分號、冒號）不得出現在標題的末尾，而標號（引號、括號、破折號、省略號、書名號、著重號、間隔號、歎號、問號）可以。
三、推薦工具
建議使用 VSCode 編寫 Markdown。
1. VSCode
如果您使用 VSCode 書寫 Markdown，建議安裝以下外掛以提高書寫效率，並使之符合開發者中心格式規範。
（1）Paste Image
支援將圖片貼上至 md 檔案中，並把圖片檔案統一儲存到 md 檔案同級的 img 目錄下。
（2）Markdown All in One
支援各類快捷鍵、預設配置、表格格式化及預覽等。
（3）markdownlint
規範 Markdown 文件格式，確保團隊格式一致，且完美相容開發者中心格式要求。
建議配置：
"markdownlint.config": {
"MD024":false,
"MD047":false,
"MD034": false,
"MD033": false,
}
（4）AutoCorrect
用於「自動糾正」或「檢查並建議」文案，給 CJK（中文、日語、韓語）與英文混寫的場景，補充正確的空格，同時嘗試以安全的方式自動糾正標點符號等等。
2. LLM (GPT)
LLM 在文件書寫過程中，可承擔修改錯字、文件潤色等功能，以提高文件輸出質量，以下案例僅供參考：
（1）更正
角色提示詞設定參考如下：
你既是語文老師，又是內容安全稽核專家，請根據我輸入的內容，判斷其是否存在以下問題：
1. 錯別字。
2. 語義明顯不通順。
3. 包含敏感資訊，如使用者名稱、密碼、網路 IP、銀行卡賬號等。
若存在上述問題請單獨指出，無需輸出修改後的內容。
（2）潤色
你是一個專業的文章潤色師，請修改和潤色我輸入的內容，確保輸出內容語言流暢、邏輯清晰、格式正確和表達效果好。
四、引文
阮一峰 - 中文技術文件的寫作規範
MDN - 文件書寫規範
Google Developer Documentation Style Guide