技术文档工程师修炼

Diátaxis 是一种思考和创作文档的方式。 Diátaxis 解决与文档内容（写什么）、风格（如何写）和架构（如何组织）相关的问题。 教程 - 学习导向 教程是一种课程，通过一系列的步骤引导读者完成某个项目。 旨在帮助初学者掌握特定技能或概念。 提供详细的指导，通常包括示例、演示和互动元素，以促进读者的实际学习体验。 操作指南 - 任务导向 操作指南提供了解决现实世界问题所需步骤的指南。 侧重于帮助用户达到特定目标，如完成某项任务或解决具体问题。 提供明确的步骤和操作建议，以使用户能够迅速、准确地执行特定任务。 参考 - 信息导向 参考指南描述产品和操作产品的技术细节。 提供深入的技术描述、规范和详细的产品信息。 可包括 API 文档、配置选项、参数说明等，以满足用户对产品内部工作原理的深入了解。 解释 - 理解导向 解释是对特定主题进行深入讨论，澄清和照亮相关概念。 目的是帮助读者更深入地理解产品、技术或相关主题。 可包括概念解释、背景知识、原理说明等，以满足用户对更广泛知识领域的渴望。 注: 更多详细内容可参考 https://librehugohu.github.i ...

文档具体的类型： 产品和手册介绍 产品的简要概述和目标受众。 说明手册的结构和如何使用手册。 安装和配置 详细说明如何安装和配置产品。 确保用户能够迅速开始使用产品。 入门指南 提供初次使用产品时的简明步骤。 强调核心功能，帮助用户快速上手。 界面导览 描述产品界面的各个部分和元素。 提供界面截图，帮助用户了解产品布局。 功能说明 对产品的各项功能进行详细说明。 包括每个功能的用途和操作步骤。 常见问题解答 收集并回答用户可能遇到的常见问题。 提供解决方案和问题排查建议。 故障排除 提供针对常见问题的详细故障排除指南。 包括错误消息的解释和解决方法。 技术支持信息 提供获取技术支持的途径，如联系信息、在线支持等。 更新日志 列出产品的版本历史和更新内容。 帮助用户了解产品的演变和改进。 术语表 解释产品中使用的专业术语和缩略语。 有助于用户理解文档中的技术术语。 安全信息 针对某些产品，提供使用时的安全注意事项。 包括警告、禁止事项等信息。 法律声明 包括关于产品使用的法律责任和免责声明。

提高产品价值文档作为产品的一部分，可以为用户提供详细的信息，帮助他们更好地理解和使用产品。清晰、易懂的文档能够降低用户的学习成本，提高他们的满意度，从而间接地提高了产品的整体价值。 释放产品潜力好的文档不仅仅是功能列表，还应提供实际的使用场景、最佳实践和操作步骤。通过指导用户如何充分利用产品功能，文档可以帮助用户发现产品的潜在价值，实现更高效的工作流程。 建立客户信心用户通常通过文档来了解产品的专业性和质量水平。清晰、准确、完善的文档传递了一种专业和用心的形象，这有助于建立用户对产品的信心，并提高他们的满意度。 推动销售在商业环境中，文档和支持的质量直接影响购买决策。有充分文档支持的产品通常更容易被市场接受，而用户在购买前也更愿意选择有详尽文档的产品，因为这意味着他们在使用过程中能够得到更好的支持。 减轻客户支持负担即使最完善的产品也难免有用户需要帮助的时候。通过提供清晰、全面、简洁的文档，您可以使用户更容易自己找到解决问题的方法，从而减轻客户支持团队的工作负担，提高整体效率。

1.需求分析需求分析是指对搜集来的需求和信息进行详细的归纳和分析。 需求有两个来源，一个是由内而外的需求，即公司想呈现哪些内容给用户；另一个是由外而内的需求，即用户想看到哪些内容。 2.文档架构设计文档架构设计是为了让用户以最方便的方式获取所需信息，解决问题。 在设计文档架构之前，建议先研究竞品资料，总结其结构和内容。根据竞品和需求，设计出一版文档架构，并通过相关人员评审，逐步迭代至最终版本。这一阶段的目标是确保文档结构合理，能够满足用户和公司的需求。 3.写作写作阶段是按照设计好的文档架构，遵循文档写作规范和理论进行内容编写的过程。 需要根据文档的结构，有条不紊地填充内容。关注清晰度、简洁性和准确性，确保文档能够有效地传达信息。 4.质量控制质量控制是检查文档的正确性、一致性和完整性。 文档也是产品，此阶段需要产品、研发、测试、文档共同参与文档的测试、审核和验证。 5.发布发布是将文档进行包装，根据需要将源内容转换成WORD、PDF或HTML。 在发布之前，确保文档已经经过充分的质量控制，并且符合发布标准。 6.交付交付是文档包装完成后，将文档交付到用户手中的过程。确保交付的文档能 ...

标题层级标题分为四级。 一级标题：文章的标题 二级标题：文章主要部分的大标题 三级标题：二级标题下面一级的小标题 四级标题：三级标题下面某一方面的小标题 下面是示例。 1234567# 一级标题## 二级标题### 三级标题#### 四级标题 原则（1）一级标题下，不能直接出现三级标题。 示例：下面的文章结构，缺少二级标题。 123# 一级标题### 三级标题 （2）标题要避免孤立编号（即同级标题只有一个）。 示例：下面的文章结构，二级标题 A只包含一个三级标题，完全可以省略三级标题 A。 12345## 二级标题 A### 三级标题 A## 二级标题 B （3）下级标题不重复上一级标题的名字。 示例：下面的文章结构，二级标题与下属的三级标题同名，建议避免。 123## 概述### 概述 （4）谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。 如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。 示例：下面的结构二要好于结构一。结构一适用的场景，主要是较长篇幅的内容。 12345678910111213141516171819结构 ...

文本字间距（1）全角中文字符与半角英文字符之间，应有一个半角空格。 123错误：本文介绍如何快速启动Windows系统。正确：本文介绍如何快速启动 Windows 系统。 （2）全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。 123正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。 半角的百分号，视同阿拉伯数字。 123正确：今年我国经济增长率是6.5%。正确：今年我国经济增长率是 6.5%。 （3）英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。 123例1：一部容量为 16 GB 的智能手机例2：1 h = 60 min = 3,600 s （4）半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。 123错误：他的电脑是 MacBook Air 。正确：他的电脑是 MacBook Air。 句子（1）避免使用长句。 不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个 ...

段落原则 一个段落只能有一个主题，或一个中心句子。 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。 一个段落的长度不能超过七行，最佳段落长度小于等于四行。 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。 段落之间使用一个空行隔开。 段落开头不要留出空白字符。 引用引用第三方内容时，应注明出处。 1One man’s constant is another man’s variable. — Alan Perlis 如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。 1本文转载自 WikiQuote 使用外部图片时，必须在图片下方或文末标明来源。 1本文部分图片来自 Wikipedia

数值半角数字阿拉伯数字一律使用半角形式，不得使用全角形式。 123错误：这件商品的价格是１０００元。正确：这件商品的价格是 1000 元。 千分号数值为千位以上，应添加千分号（半角逗号）。 1XXX 公司的实收资本为 ￥1,258,000 人民币。 对于 4 位的数值，千分号是选用的，比如1000和1,000都可以接受。对于 4 位以上的数值，应添加千分号。 货币货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。 12$1,0001,000 美元 英文的货币名称，建议参考国际标准 ISO 4217。 数值范围表示数值范围时，用波浪线（～）或一字线（—）连接。参见《标点符号》一节的“连接号”部分。 带有单位或百分号时，两个数字建议都要加上单位或百分号。 123132 kg～234 kg67%～89% 变化程度的表示法数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。 12345增加到过去的两倍（过去为一，现在为二）增加了两倍（过去为一，现在为三） 数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。 12345降低 ...