# 如何写好一篇技术文档

本篇对网上技术文档写法整理，加自我理解，希望能让自己写的文章越来越好

# 前言

​ 写技术文档需要明白技术是很抽象的东西，理解起来也是理解起来很有难度的东西。想要靠纯文字进行内容转述，是很困难的。所以，应该更多地借助表格和图片，甚至 gif 动图，帮助读者理解。所谓 “字不如表、表不如图”

# 技术文档分类

​ 软件领域内文档可分为：教程、操作指南、解释、技术参考 它们有不同目的、功能，且编写也有不同方式。

​ 关系如下图：

​ 教程和操作指南类似，因为它们都关注描述实际步骤，而操作指南与技术参考交集是我们在工作层面，编码， 参考指南和说明是相似的，因为它们关注理论知识，最后，教程与解释的共同之处在于它们在我们学习时最有用，但却不是实际应用。

文档每个功能 (象限) 特征与相邻象限特征重叠，因为这些重叠，不同类型文档变得混淆甚至相互混合也就不足为奇了

大量文档呈现四个象限中一个，按照 4 个象限完全区分开很难找到，虽然很难找到例子。Django 是符合文档结构的例子：Django , and django CMS.

# 教程

​ 教程像一门课程，完全以学习为向导，向初学者展示项目功能，指导初学者执行一系列动作来达到某些目标。教程的目的是在学完后，初学者理解应用及软件本身。教程不单单是传授学习知识，更倾向于教授如何学习。且教程会决定结果，用户以后的行为，对初学者而言，教程结果不但是 “有意义”，而且也是 “可实现的”，“可操作的”。

# 如何写好教程

​ 教程选取上需先关注用户所需要的实践，实践过程具备重复性、严谨性，能让任何一个初学者按教程步骤操作成功。确定实践后关注具体步骤，而非抽象概念。用户通过实践学习，最好每个步骤用户都能立刻看到效果，确认教程有效。关键是让学习者开始他们的旅程 ，而不是以成功完成所有步骤为目的。教程中提供仅向用户解释为了完成教程需要的知识的最低解释。因为解释是用户理解教程的障碍，合理的做法是：在需要的地方适度解释。

# 操作指南

​ 操作指南完全是以目标为导向，用于解决特定的问题。这种文档相对好些很多。因为在操作指南文档中都是假设用户已经知道如何执行基本操作并使用基本工具。仅需要描写实现目标的步骤。

如：做菜指南类的书，它已经假设了你懂油米醋盐等做饭常识，于是菜谱上只用说明每道菜特定的步骤，每道菜的工序

# 如何编写操作指南

​ 涉及到操作指南文档时，可以假设读者知道他们应该实现什么但是还不知道如何做。所以操作指南必须解决特定问题，注重如何获得结果的其他都是次要，不需要有详细的解释，而指南内的文档标题要告诉用户它的确切功能，内容是从一个合理的起点开始必须包含一系列步骤，需要按顺序执行。步骤中应该有适度的灵活性，但不要面面俱到，实用性比完整性更有价值，而且指南不应解释和操作无关内容，如果解释很重要，请在其它地方进行。指南需要可靠的，但它们不需要具有教程的那样严谨的可重复性

# 解释文档

​ 解释文档以理解作为基本向导，用于澄清和阐明特定主题。解释很少在文档中有章节，一般存在于背景或其他注释中，它从更广的视角，从更高层次甚至从不同角度阐明软件，以描述或讨论问题的背景和关联内容，从而说明问题，解释问题。解释文档可以在闲暇时阅读，而不用关注代码和实现，解释主体不是根据特定的任务去设定，解释有时包含主观色彩

如：在一个菜谱书内有一篇讲述烹饪社会历史的文章

# 如何写解释文档

• 解释一般在说明背景和连接上下文 - 例如，* Web 表单以及如何在 Django 或 Search 和 django CMS 中处理它们。它们解释为什么 * 事情是如此 - 设计决策，历史原因，技术限制。

• 解释讨论提供替代方案或意见

• 不要指导或提供技术参考。这不提供用户如何做某事的解释。 它也不提供技术描述。 这些功能已在其他部分中处理。

# 技术参考

​ 技术参考指南以信息作为基本导向，提供丰富信息，严肃而中肯，文档要准确且完整。唯一作用是叙述，描述工作的原理，是开发人员认为是提供关于软件的技术信息指南。

如：jdk1.8 的开发文档

# 如何写技术参考指南

​ 参考指南的唯一目标是尽可能清楚，完整地描述。其他任何事情（解释，讨论，指导，推测，意见）不仅会影响阅读，而且会使其更难以使用和维护。可以有示例。不允许对主题的概念或讨论进行解释。 当然，在需要的地方，可链接到操作指南，说明和入门教程。

​ 文档描述必须准确且保持最新状态。 实现和描述之间的任何差异都将不可避免地导致用户 "误入歧途"。在参考指南中，布局，笔调，格式 与要与同类百科全书或字典的保持一致。参考指南内容与代码库保持相同的目录结构，以便用户能够代码和文档相互对照。

# 文档书写规范

# 标题

• 文章有且仅有 1 个一级标题
• 标题统一采用「#」标记
• 标题逐级递增（例如避免在一级标题下直接新增三级标题）
• 标题的「#」标记和文本之间必须要有 1 个空格，否则类似掘金平台无法识别标题
• 标题和子标题内容避免完全一致
• 标题避免有标点符号 ".,;:!?。，；：！？"
• 标题前后应该有空行
• 标题避免缩进
• 避免出现四级标题，保持简洁
• 避免出现孤儿标题
• 不要使用加粗代替标题
• 如果当前标题下内容过于简洁（例如只有一个简短的段落），可以需要考虑去除标题

温馨提示：标题的作用不仅仅是使读者可以了解文章的整体结构，更多的是可以使读者快速跳转到他想要阅读的部分。

# 列表

• 无序列表统一采用「-」标记
• 首级列表避免缩进，次级列表缩进 2 字符
• 列表前后应该有空行
• 简短的同类型内容进行描述时尽量采用列表的呈现形式（简洁、美观且富有逻辑）

# 代码块

• 在代码块中展示 Shell 命令不需要在命令行前加「$」符号，除非同时需要打印输出信息
• 代码块前后应该有空行
• 代码块必须指定语言类型
• 如果部分代码引用其他的技术文章，则需标明作者和来源链接

# 引用

• 引用标记和内容之间避免有多个空格
• 引用前后应该有空行
• 温馨提示的内容可以采用引用的呈现形式

# 文本

• 当前文本末尾不产生多余的空格
• 不要在文本中使用 HTML 标记
• 不要在文本中直接暴露网址，如果需要可采用 <url> 形式
• 不要有空白链接，例如 [link desc]()
• 英文单词需要有正确的大小写，例如 JavaScript、Android、iOS、iPhone、Google、Apple
• 图片必须有描述文字
• 数字、英文以及英文单位等需要和中文保持 1 个空格，例如：今天是 2020 年 5 月 13 日
• 第一次出现需要解释的缩写术语时在括号中给出英文全名和中文解释，例如 AJAX（ Asynchronous JavaScript And XML，异步 JavaScript 和 XML ）
• 解释性内容可以紧贴文本放在括号后面（这个括号里的内容就是一个解释性内容）
• 如果语句过长，尽量精简到最短
• 除了「%」、「°C」以及倍数单位（例如 2x、3n）以外，其余的数字和单位之间需要保持 1 个空格
• 中文或中英文混排时，一律使用中文 / 全角标点
• 尽量避免使用「!」或「~」，请理性的书写技术文章
• 如果引用别人的图片，那么必须标明图片的来源和链接
• 尽量避免在文本中出现「我」、「我觉得」、「个人觉得」、「我认为」等带有主观色彩的叙述
• 尽量使用主动语态，避免被动语态
• 中文的标点符号和其他字符之间一律不加空格

# 段落

• 段落之间不要产生多个连续的空白行
• 如果部分段落引用其他的技术文章，则需标明作者和来源链接
• 段落开头避免缩进

# 文章

• 如果文章全篇转载，请在全文开头显著位置注明出处并链接至原文
• 如果文章内容过多，那么可以根据内容类型进行分篇处理（保持读者的阅读耐心）

# 切忌以下问题

• 罗列大量术语：全无背景介绍，直接开始罗列一堆概念
• 粘贴长篇代码：大篇幅引用代码，影响阅读体验
• 风格变化无常：时而严肃、学术风，时而卖萌、抖机灵
• 内容贪图简便：使用代码块、图片或 blockquote 完全取代正文

# 总结

​ 写文章除了文档必要书写规范，还需要考虑自己写文章的初衷，适合人群，内容结构，文章内容最好语言易读，内容表现力上文字不如表格，而表格不如图形。这三者在表现力上各有各的侧重点，需要根据不同的场景需要来选取使用。

# 参考文档

• 技术文章的写作技巧分享
• 如何编写技术文档，你所不知道的秘密