文档是技术产品的重要组成部分，撰写各类技术文档应成为研发人员的日常工作之一。对于个人而言，书写文档不仅有助于提高写作水平，还能在写作过程中重新梳理产品架构，查缺补漏。对于团队来说，文档有助于知识共享和传递，提高开发与协作效率，保证项目后期的可维护性。文档是产品与用户之间的桥梁，是用户了解、学习和使用产品的关键媒介，有助于提升产品力和用户信心。建议研发人员在产品研发过程中，重视文档的积累和输出，以保证产品的长期、健康和可持续发展。
本指南仅包含约束技术文档的基本要求，以尽可能地确保文档语言和风格的一致性。
一、基本要求
1. 内容
语言表达清晰流畅，内容全面且成体系。
2. 格式
建议原始文档用 Markdown 格式书写并存档，使文档不依赖特定展示平台，便于传播及分享。
3. 组成部分
一个项目中的技术文档至少包含以下两类：
（1）用户手册：向用户介绍产品及其使用方法，以帮助用户快速了解产品功能并掌握使用方法。
（2）技术手册：提供详细的技术信息，如技术选型、设计方案、使用规范、测试报告、部署配置等文档，既能规范开发过程、支持团队协作，也能帮助用户更好地理解和使用产品。
此外建议添加项目文档，用于记录项目执行过程中相关资料，如项目计划、会议纪要等。
4. 文档体系
可参考如下文档体系结构：
bash
├── 简介（Introduction）：[必备] 提供对产品和文档本身的总体的、扼要的说明
├── 快速上手（Getting Started）：[可选] 如何最快速地使用产品
├── 入门篇（Basics）：[必备] 又称"使用篇"，提供初级的使用教程
│ ├── 环境准备（Prerequisite）：[必备] 软件使用需要满足的前置条件
│ ├── 安装（Installation）：[可选] 软件的安装方法
│ ├── 设置（Configuration）：[必备] 软件的设置
├── 进阶篇（Advanced)：[可选] 又称"开发篇"，提供中高级的开发教程
├── API（Reference）：[可选] 软件 API 的逐一介绍
├── FAQ：[可选] 常见问题解答借鉴案例：YApi
二、书写规范
以下内容主要参考自 阮一峰 - 中文技术文档的写作规范
1. 标题
建议最多只支持四级标题：
（1）一级标题：文章的标题，建议有且仅有一个
（2）二级标题：文章主要部分的大标题
（3 三级标题：二级标题下面一级的小标题
（4）四级标题：三级标题下面某一方面的小标题，谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节
示例：
bash
# 文档名称
## 一、二级标题
### 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 目录下。
支持各类快捷键、默认配置、表格格式化及预览等。
（3）markdownlint
规范 Markdown 文档格式，确保团队格式一致，且完美兼容开发者中心格式要求。
建议配置：
bash
"markdownlint.config": {
"MD024":false,
"MD047":false,
"MD034": false,
"MD033": false,
}（4）AutoCorrect
用于「自动纠正」或「检查并建议」文案，给 CJK（中文、日语、韩语）与英文混写的场景，补充正确的空格，同时尝试以安全的方式自动纠正标点符号等等。
2. LLM (GPT)
LLM 在文档书写过程中，可承担修改错字、文档润色等功能，以提高文档输出质量，以下案例仅供参考：
（1）更正
角色提示词设置参考如下：
bash
你既是语文老师，又是内容安全审核专家，请根据我输入的内容，判断其是否存在以下问题：
1. 错别字。
2. 语义明显不通顺。
3. 包含敏感信息，如用户名、密码、网络 IP、银行卡账号等。
若存在上述问题请单独指出，无需输出修改后的内容。（2）润色
bash
你是一个专业的文章润色师，请修改和润色我输入的内容，确保输出内容语言流畅、逻辑清晰、格式正确和表达效果好。