技术写作 第二课

目标读者

本课程的目标读者为已完成技术写作 第一课，但是仍然渴望进行更多写作培训的人员。如果你没有接受过任何技术写作的培训，最好先看一下第一课能容。

学习目标

这节课侧重于技术写作中的几个中间主题，学习完本课程之后，将收获如下的知识：

• 从几种不同的策略中选择一种编写第一稿的策略，以及第二稿、第三稿的其他策略。

• 使用多种技术来检测写作中的错误。

• 学会组织大型的文档。

• 介绍文档的范围和所有先决条件。

• 写下清晰的图形标题。

• 在技术插图中选择适当的信息密度。

• 将读者的注意力集中在插图上。

• 通过图片建立上下文。

• 有效的修改技术插图。

• 创建有用、准确、简洁，清晰，可重用和注释良好的代码，用来演示一系列的复杂性。

• 标示不同的文档类型。

• 描述所有的内容。

• 体谅初学者，并为他们编写教程。

成为一名优秀的工程师或者优秀的技术作家都需要花费多年的专注实践，这门课程能提高你的写作水平，但不会立即使你成为一个出色的作家。

自我编辑

参考《Google开发分档风格指南》

换位思考：

• 尝试从读者的角度阅读文档，确保文档目的是明确的；并考虑好不同的角色所拥有的知识储备。

• 然后从作者的角度阅读文档，确保你做的假设有用，还可以提供资源的链接。

• 最后请注意，过分依赖角色，会导致文档过于狭隘，而无法对大多数读者有用。

大声读出来：

• 自己大声的朗读或者使用屏幕阅读器朗读，来听取尴尬的措辞，冗长的句子或其他不自然的内容。

编写每一搞的策略：

• 编写完每一个版本之后，先放边上一个小时，然后再回来阅读一遍，总会发现有可以改进的地方，推荐做三遍。

检查写作中的错误：

• 邀请某人查看你的文档，并给你具体的，建设性意见。

• 阅读的人不一定是同行，但是最好熟悉你遵循的文档风格。

写一个大型文档

使用以下策略可以帮助你们撰写大型文档：

• 选择编写单个大型文档或一组简短文档。

• 把简短文档整理为一个大型文档。

• 给大型文档添加导航。

• 逐步暴露信息。

什么时候写大文档：

• 当你的阅读对象是刚入门的读者时，写操作指南、入门概述和概念性指南通常能以短文的形式提供更好的作用。

• 当已经对工具和主题有一定经验的读者，写深入教程，最佳实践指南和命令行参考页可以作为更长的文档使用。

• 好的教程能可以依靠叙述来引导读者完成较长文档中的一系列相关任务。

写较长文档的方法：

• 创建大纲和起草宣言。

• 完成初稿之后，可以更具概述和简介对其进行复审。

编写大纲的实用技巧：

• 在要求读者执行任务前，先解释为什么要执行此任务。

• 将大纲的每个步骤限制为描述概念或完成特定任务。

• 构造轮廓，以便文档在与读者最相关时引入信息。

• 在起草前，先与贡献者共享大纲内容。

可以提供一个基本信息来介绍文档：

• 说明文档涵盖的内容。

• 希望读者具备哪些知识储备。

• 说明文档没有涵盖那些内容。

为文档添加目录，可确保读者能快速的找到所需要的内容，清晰的目录包括：

• 简介和摘要

• 主题清晰

• 有助于用户理解的标题和子标题

• 提示用户在目录中的位置

• 可以通过目录能跳转到相关位置

• 有下一步学习的链接

在每个标题下都进行简短的介绍，避免在标题后面马上放入下一级标题。

图片

在插入图之前写标题会很有帮助，然后，插入能说明标题的图片

图片中好的标题应该具有下面的特征：

• 他们很简短，通常只是几句话。

• 说明了重点。

• 能吸引读者的注意力。

考虑以下三个图形，每个图形使用相同的标题。

标题A。单链接列表包含内容和指向下一个节点的指针。

image

标题B。单链接列表包含内容和指向下一个节点的指针。

image

标题C。单链接列表包含内容和指向下一个节点的指针。

上述三个标题中标题C是最具启发性的，标题清晰的描述了图片的功能。

如下图片中的信息量不要过大。

image

如上图的复杂性就会让很多读者望而却步，就像避免过长的句子一样，请尽量避免较复杂的图片。

将复杂的图片变为连贯且有用的诀窍是将复杂的系统组织成子系统。

图4.分为三个子系统的复杂系统。

显示大图之后再分别提供每个子系统的图片。

图5.复杂系统的一个子系统的扩展细节。

画图工具

• Google绘图

• diagrams.net

• lucidchart

  创建示例代码

  代码仍然是技术人最喜欢读的，好的代码通常是最好的文档。

  好的代码样本是正确、简洁，你的读者可以快速理解它们，并能以最小的代价重复使用它们。

  正确

  示例代码应该满足下面条件：

  • 代码构建没有错误。

  • 能按要求进行执行。

  • 要做好生产使用的准备，比如，代码不能有安全漏洞。

  • 遵循语言的约定。

  简洁

  示例代码应该简短，仅包括基本组件，不相关的代码可能会使你的读者分散注意力。但是，也不要用错误的做法来缩短你的代码，在正确和简短之间，我们更看重正确性。