文档是技术产品的重要组成部分，撰写各类技术文档应成为研发人员的日常工作之一。对于个人而言，书写文档不仅有助于提高写作水平，还能在写作过程中重新梳理产品架构，查缺补漏。对于团队来说，文档有助于知识共享和传递，提高开发与协作效率，保证项目后期的可维护性。文档是产品与用户之间的桥梁，是用户了解、学习和使用产品的关键媒介，有助于提升产品力和用户信心。建议研发人员在产品研发过程中，重视文档的积累和输出，以保证产品的长期、健康和可持续发展。
本指南仅包含约束技术文档的基本要求，以尽可能地确保文档语言和风格的一致性。
一、基本要求
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 目录下。
支持各类快捷键、默认配置、表格格式化及预览等。
（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）润色
你是一个专业的文章润色师，请修改和润色我输入的内容，确保输出内容语言流畅、逻辑清晰、格式正确和表达效果好。 
