不写文档你就输了

作者 | Thoriq Firdaus

译者 | 王强

策划 | 小智

在移动、Web 和桌面应用或 JavaScript 库的开发领域中，文档在应用的成功之路上扮演着非常重要的角色。但如果你曾经编写过文档，就肯定会同意我的看法：编写文档是开发人员最不喜欢做的事情之一。

与编写代码（这是开发人员的本职工作）不同，文档必须能被所有人轻松理解（这里的所有人不仅是指开发人员，也包括缺乏技术背景的一般人）。从技术上讲，我们必须将机器语言（代码）翻译成普通人都可以理解的语言，这种事情说起来容易做起来却很难。

尽管这件事情可能会给你带来很大的负担，但是编写文档是很重要的环节，并且可以为你的用户、你的同事，尤其是你自己带来诸多好处。

好的文档可以帮助用户

显然，文档可以帮助读者 理解代码的工作原理。但是许多开发人员有着错误的认识，那就是他们认为软件的用户都是编程高手。在这样的假设下，他们编写的文档可能只是薄薄的几页纸，从头到尾跳过了文档本应该包含的许多要点。如果你精通编程语言，那么遇到问题还可以自己找出解决办法。如果你并没有那么专业，那么看文档时很容易就会迷失方向。

供用户使用的文档通常包括使用实践或“操作方法”的内容。为一般用户创建文档时，经验法则是 文档应该清晰直观。使用普通人也容易理解的词汇要比使用技术术语或专业习语更合适。软件的实际应用示例也是非常受用户欢迎的。

良好的文档布局设计还可以真正帮助用户轻松浏览文档的各部分内容。在这方面一些很好的例子包括 Bootstrap 的文档，和 WordPress 的“WordPress 的第一步”文档，它们也都是我最喜欢的榜样。

好的文档可以帮助其他开发人员

每位开发人员都有自己的代码风格。但在团队合作中，我们经常需要与其他同事共享代码。因此大家有必要 达成共识，形成一套标准，以使所有人保持一致。精心编写的书面文档会是团队必要的参考。

但与最终用户文档不同，这类文档通常会描述代码命名约定之类的技术流程，展示开发人员应如何构造特定页面，以及 API 如何工作，外加一些代码示例。通常，我们还必须在代码内编写文档（称为注释），以描述所注释代码的作用。

此外，如果以后有新成员加入团队，这类文档可以是培训他们的一种省时有效的方法，这样你就不必为新人一对一地讲解代码了。

好的文档也可以帮助开发人员自己

关于编程的有趣之处在于，有时 甚至开发人员自己也不理解他们编写的代码。尤其是当开发人员几个月甚至几年都没再碰过自己写过的代码时，他们突然回来看自己的作品会感到十分陌生。

如果出于某种原因，开发人员需要重新审阅以前的代码，他们往往会怀疑自己在编写这些代码时到底在想些什么。别惊讶：我以前就曾遇到过这种情况。在这种情况下，我肯定会希望自己给代码写下了良好的文档。

给你的代码写好文档的话，你就能够快速深入到代码的底层，不会有那么多疑惑，从而节省许多时间。省下来的这些时间可以拿来完成更改工作。

好的文档有哪些特性？

有几个因素可以帮助你构建出良好的文档。其中一些最重要的因素如下：

1. 永远不要假设

不要以为你知道的东西用户也知道，或者他们很清楚自己应该了解的内容。无论用户的熟练程度如何，总是 从头开始解释各种事情 是更好的选择。

例如，如果你构建了一个 jQuery 插件，则可能会从 SlickJS 的文档 中汲取灵感。它介绍了如何构造 HTML、放置 CSS 和 JavaScript 的位置、从头开始讲解如何初始化 jQuery 插件，甚至还展示了添加所有这些内容后的完整最终标记，所有东西都写得清清楚楚。

最重要的是，文档应该是根据用户而不是开发人员的思考过程来编写的。以这种方式处理你自己的文档，将为你提供一个更好的视角来组织自己的代码。

2. 遵守标准

在添加与代码内联的文档时，请使用 代码编程语言所期望的标准。 我们应该总是解释每个函数、变量以及函数返回的值都是什么意思。下面是一个很好的 PHP 内联文档示例。

/** * Adds custom classes to the array of body classes. * * @param array $classes Classes for the body element. * @return array */function body_classes( $classes ) {  // Adds a class of group-blog to blogs with more than 1 published author.  if ( is_multi_author() ) {    $classes[] = 'group-blog';  }
  return $classes;}add_filter( 'body_class', 'body_classes' );

以下是使用 PHP、JavaScript 和 CSS 的最佳实践来格式化内联文档的一些参考：

• PHP：WordPress 的 PHP 文档标准
• JavaScript： UseJSDoc
• CSS： CSSDoc

如果你使用的是 SublimeText，我建议你安装 DocBlockr，它将用内联文档巧妙地预填充你的代码。

3. 图形元素

文档中应该多用图形元素，它们比文本更直观。这些媒介很有用，特别是当你使用图形界面构建软件时。你可以添加指向性元素，例如箭头、圆圈或 任何可以帮助用户直观地弄清楚如何完成这些步骤的元素。

以下是 Tower 应用中的 示例，你可以从中汲取灵感。它们很好地解释了如何用优雅的方式来做版本控制工作，比纯文本命令行更容易理解。

4. 分区

你可以考虑将文档中的一些内容包装在项目符号列表和表格中，因为这样可以让用户更容易浏览较长的内容，更方便快速定位。

添加目录，并将文档拆分为一些容易理解的部分，同时要让各个部分与接下来的内容保持关联。内容应该简短明了。以下是 Facebook 中一份组织良好的 文档示例。

我们可以点击目录元素，直接跳转到对应内容。

5. 修订和更新

最后，文档写好后要仔细查看文档中是否有错误，并在必要时，或在产品、软件或库发生重大更改时修订文档。如果不随产品一起定期更新，那么你的文档对任何人都是没用的。

原文链接:

https://www.hongkiat.com/blog/why-documentation-essential/

---

InfoQ 读者交流群上线啦！各位小伙伴可以扫描下方二维码，添加 InfoQ 小助手，回复关键字“进群”申请入群。回复“资料”，获取资料包传送门，注册 InfoQ 网站后，可以任意领取一门极客时间课程，免费滴！大家可以和 InfoQ 读者一起畅所欲言，和编辑们零距离接触，超值的技术礼包等你领取，还有超值活动等你参加，快来加入我们吧！

• 
  

  
  

  
  

  点个在看少个 bug 👇