文檔是技術產品的重要組成部分，撰寫各類技術文檔應成為研發人員的日常工作之一。對于個人而言，書寫文檔不僅有助于提高寫作水平，還能在寫作過程中重新梳理產品架構，查缺補漏。對于團隊來說，文檔有助于知識共享和傳遞，提高開發與協作效率，保證項目后期的可維護性。文檔是產品與用戶之間的橋梁，是用戶了解、學習和使用產品的關鍵媒介，有助于提升產品力和用戶信心。建議研發人員在產品研發過程中，重視文檔的積累和輸出，以保證產品的長期、健康和可持續發展。

本指南僅包含約束技術文檔的基本要求，以盡可能地確保文檔語言和風格的一致性。

一、基本要求

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

?轉自https://www.cnblogs.com/zengzuo613/p/18589348