文档是技术产品的重要组成部分，撰写各类技术文档应成为研发人员的日常工作之一。对于个人而言，书写文档不仅有助于提高写作水平，还能在写作过程中重新梳理产品架构，查缺补漏。对于团队来说，文档有助于知识共享和传递，提高开发与协作效率，保证项目后期的可维护性。文档是产品与用户之间的桥梁，是用户了解、学习和使用产品的关键媒介，有助于提升产品力和用户信心。建议研发人员在产品研发过程中，重视文档的积累和输出，以保证产品的长期、健康和可持续发展。
本指南仅包含约束技术文档的基本要求，以尽可能地确保文档语言和风格的一致性。
一、基本要求
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