作者 |

译者| 王强

规划| 小智

在移动、Web 和桌面应用程序或库开发领域，文档对于应用程序的成功起着非常重要的作用。 但如果您曾经编写过文档，您就会同意我的观点：编写文档是开发人员最不喜欢做的事情之一。

与编写代码（这是开发人员的工作）不同，文档必须易于每个人理解（这里的每个人不仅指开发人员，还包括没有技术背景的普通人）。 从技术上来说，我们要把机器语言（代码）翻译成普通人能理解的语言，这说起来容易做起来难。

虽然编写文档可能会给您带来沉重的负担，但它是重要的一步sublime text 3 js代码格式化，可以给您的用户、您的同事，尤其是您自己带来很多好处。

好的文档可以帮助用户

显然，文档可以帮助读者理解代码的工作原理。 但很多开发人员有一个错误的认识，那就是他们认为软件的用户就是编程专家。 在这种假设下，他们写的文档可能只是几页薄页，跳过了文档应包含的许多要点。 如果你精通编程语言，你可以自己找到问题的解决方案。 如果你不是那么专业，在阅读文档时很容易迷失方向。

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

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

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

每个开发人员都有自己的编码风格。 但在团队合作中，我们经常需要与其他同事共享代码。 因此，有必要让大家达成共识，形成一套标准，让大家步调一致。 写得好的文档将成为团队必要的参考。

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

此外，如果将来有新成员加入团队，这种类型的文档可以成为培训他们的一种节省时间且有效的方法，因此您不必一对一地向新人传授代码。

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

编程的有趣之处在于，有时甚至开发人员自己也无法理解他们编写的代码。 尤其是当开发人员几个月甚至几年没有碰过自己写的代码时，突然回来看自己的作品时，会感觉很奇怪。

如果由于某种原因开发人员需要重新访问以前的代码，他们常常想知道自己编写代码时的想法。 不要感到惊讶：我以前也遇到过这种情况。 在这种情况下，我绝对希望我为代码编写了良好的文档。

如果你为代码编写了良好的文档，那么你可以快速了解代码的底层，而不会产生太多疑问，从而节省大量时间。 节省的时间可以用来完成更改。

好的文档有哪些特征？

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

1. 永远不要假设

不要假设如果您知道某件事，用户也知道它，或者他们知道他们应该知道什么。 无论用户的熟练程度如何，从一开始就解释各种事情总是更好。

例如sublime text 3 js代码格式化，如果您构建一个插件，您可能会从 . 它展示了如何构建 HTML、在哪里放置 CSS 和 CSS、解释如何从头开始初始化插件，甚至在添加所有这些内容后显示完整的最终标记，所有这些都写得很清楚。

最重要的是，文档应该根据用户的思维过程来编写，而不是开发人员。 以这种方式处理您自己的文档将使您更好地了解如何组织自己的代码。

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 和 CSS 格式化内联文档的最佳实践的一些参考：

：

CSS：

如果您正在使用它，我建议安装它，它将用内联文档整齐地预先填充您的代码。

3.图形元素

图形元素应该在文档中更频繁地使用，因为它们比文本更直观。 这些媒介很有用，特别是当您使用图形界面构建软件时。 您可以添加方向元素，例如箭头、圆圈或任何可以帮助用户直观地了解如何完成步骤的元素。

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

4、分区

您可以考虑将文档中的某些内容包装在项目符号列表和表格中，因为这使用户可以更轻松地扫描较长的内容并更轻松地快速导航。

添加目录并将文档分成易于理解的部分，同时保持每个部分与后续内容相关。 内容应该简短明了。 下面是一个组织良好的文档的示例：

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

5. 修订和更新

最后，文档编写完成后，仔细检查是否有错误，并在必要时或当产品、软件或库发生重大更改时进行修改。 如果它没有与产品一起定期更新，那么您的文档对任何人都毫无用处。

如有侵权请联系删除！