为你的 JavaScript 项目编写文档

• 为什么文档很重要？
• 写什么？
• 加速进程的工具
• JavaScript 项目文档的优秀示例
• 概括

如今，作为一名 Web 开发者，你很少会从零开始构建任何东西：你的日常工作主要是集成各种 JavaScript 库。如果你正在构建一个 Web 应用，你很可能会使用一些框架，例如 React、Vue 或 Angular 作为前端。为了传输和管理数据，你将使用 Redux 或 GraphQL。对于后端，你会使用 Express，可能还会使用 Loopback。然后，你需要用测试覆盖所有内容，所以 Jest、Mocha 或 Jasmine 也是必不可少的。最后，你还需要像 Bootstrap 这样的 UI 框架，或许还有一些图表工具。我已经统计过至少 7 个核心库，而且它们都包含在一个项目中！那么，像 JavaScript 本身、Node.js 以及可能还有 Typescript 这样的底层技术呢？嗯，真是太多了！
那么，你如何学习所有这些工具呢？当然，有文档之类的东西。

为什么文档很重要？

有两种方式可以与文档产生联系：你可以编写文档，也可以阅读文档。有时你会同时写文档和阅读文档，但大多数情况下，你正在使用其他开发人员的成果。除非这些库有完善的文档，否则你不会使用它们，对吧？这就引出了第一点：

如果你的项目没有充分的文档记录，人们甚至不会考虑它

这看起来显而易见，但如果你的代码没有文档，那么了解它功能的唯一方法就是对其进行逆向工程。你会自己动手吗？让我们考虑一个极端的例子，想象一下如果 React 没有文档会怎样。那么就只有少数极客会尝试 Facebook 的这个新工具，因为需要浏览源代码才能理解它的功能和使用方法。当然，不会有企业使用没有文档的库。什么样的 CEO 或 CTO 会愿意将公司资源冒险投入到一种上手时间难以预测的技术上呢？此外，Facebook 的工程师自己也很难支持和维护代码库，这就引出了第二点：

6个月后你将无法理解你的代码

我敢打赌，你肯定经历过那种感觉：看着几个月或几年前写的代码，一行都看不懂。甚至很难承认这段代码是你写的。听起来很熟悉？这些代码甚至可能看起来像是出自一个经验不足的人之手，看起来很傻，但你仍然无法解释其中发生了什么。你为什么要写这段代码？
那一刻，强烈的悔恨感会悄然涌上心头，你会开始意识到，编写文档的最佳时机是你编写这段代码的时候，也就是 6 个月前。现在，你不得不阅读代码而不是文档，而代码并没有回答“为什么”编写它的问题，也没有解释清楚它本身。所以，文档的主要目的是解释你为什么要编写这段软件，包括解释为什么将来你自己要编写它。

“记录是你写给未来自己的一封情书”（达米安康威）。

写什么？

在明确了文档的重要性之后，我们似乎可以开始创建文档了。不过，在继续之前，我建议先暂停一下，从零开始，明确定义你的目标受众，并了解你的项目能创造的价值。

定义你的受众

这一点看似显而易见，却常常被人遗忘。最好明确地明确你的目标受众。你的用户是谁？他们主要是开发人员还是设计师？经验丰富的还是新手？他们是在大型团队还是小型团队中使用你的项目？等等。回答这些问题将帮助你定义一个虚拟用户画像，它代表了你的大多数用户。牢记这个虚拟用户画像将​​对你大有裨益，这样编写文档的过程将更像是你们之间的对话。

你的项目解决了什么问题？

首先，你需要在文档中添加一个清晰的定义，说明项目的名称以及它解决的问题。最好用一两句话来描述。人们会从各种渠道访问你的页面，因此他们的观点也各不相同。因此，你必须非常精确地描述，避免使用模糊的描述。只需简单说明你的 JavaScript 项目是什么、它的目标用户是谁以及它解决了什么问题。你可以参考Sing App React Admin Template文档，了解如何正确定义标题和描述。

快速启动和安装步骤

大多数人不喜欢等待。你的用户也一样。让他们尽快启动并尝试你的项目。准备一份简单的项目设置步骤列表，并将其放在文档首页的顶部。通常，它可能是设置环境和启动应用程序所需的命令列表。如果可能的话，最好直接复制粘贴这些命令，然后启动整个应用程序或库。以Rails Admin 文档为例： 设置库所需的步骤列表清晰易行，这使得整个项目更具吸引力。

希望您的用户能够设置并启动一切，所以现在是时候深入了解一下了。

组件和功能文档

快速启动项目很可能不是与之交互的唯一选项。还会有其他部分、模块、组件、功能、类等等。随便你怎么说。例如，你的软件中需要单独文档并提供 API 来以某种方式与之交互的部分。

首先要做的是列出所有这些组件，并在此基础上制作一个目录，并在其后附上相关页面的链接。

对于你的每一篇文档，最好都应用与编写项目描述相同的原则：命名组件，描述其用途，安装过程（如果有）。API 方法和参数是什么（如果有）？试着将自己置于你之前描述的虚拟角色的位置，想象一下集成这个特定组件会遇到哪些问题和困难。帮助他们使用它，并且不要遗漏任何功能！

设置库所需的步骤列表清晰且易于执行，这使得整个项目更具吸引力。

希望您的用户能够设置并启动所有内容，现在是时候深入了解一下了。Firebase文档是结构化文档的绝佳示例。您可以在左侧看到所有可用文档部分的菜单，并在页面中间与特定组件进行交互。

许可和贡献说明

必须有某种东西来指导你的项目与其用户之间的关系。你必须决定你的软件在什么条件下分发和使用。网络上有很多标准许可证，因此你可以为你的项目选择合适的许可证。最流行的许可证是：BSD、MIT、Apache GNU 许可证。它们都是开源的，所以请记住这一点。专有许可证因项目而异，因此这可以另作讨论。

如果你的项目是开源的，那么你期望人们能够做出贡献。因此，你最好能给他们一些指导。告诉他们在哪里可以报告问题、提问，贡献之前有哪些限制或先决条件，在哪里可以找到问题等等。否则，你将失去一大批心怀感激的支持者和维护者。

编写文档的技巧

我们无法预测所有用例以及用户使用文档的方式。通常，一个很好的原则是始终将自己想象成用户，并以此为视角来组织所有内容。不过，以下是每个项目文档都必须遵循的几个通用技巧：

• 人们很容易复制粘贴你的代码。记住这一点，并确保亲自执行代码进行检查。避免在代码示例中放置一些不可见的字符。最好使用code和blockquote标签来嵌入代码块。
• 保持文档更新。每次代码变更都必须伴随文档的相应变更。否则，文档很快就会过时，相当于没有文档。
• 代码注释是文档的一部分。这是最后一个，也是非常重要的一点。如果你的项目是开源的，用户会通读你的代码，因此内联注释会对他们有很大帮助。此外，像JSDoc这样的工具可以根据代码注释生成文档！所以你不必在单独的文件中编写任何内容。只需将你的代码库输入到这个工具中，瞧，你就有文档了。

加速进程的工具

既然有这么多文档工具可用，为什么还要自己从头开始编写和创建所有内容呢？如今，生成文档，尤其是生成带有内联注释的高质量代码，只需运行一个命令即可。

让我们概述一下 2019 年可用的文档工具。

JS文档

JSDoc 是最流行的 JavaScript 文档生成器。您只需运行 jsdoc 命令，并将文件名作为参数即可。它会自动生成包含可立即使用的文档的 HTML 文件。其网址为https://github.com/jsdoc/jsdoc。

多库萨乌斯

Docusaurus 是一款更复杂的工具，它允许您基于包含文档内容的 Markdown 文件生成完整的文档网站。它基于 React 并支持版本控制，因此您可以轻松维护过去生成的文档的不同版本。其他重要优势包括嵌入式搜索和多语言支持，这对于流行的存储库至关重要。其网址为https://docusaurus.io/。

api文档

apiDoc 会根据源代码中的 API 注释创建文档。它是一个非常棒的工具，可以为包含并公开大量 API 方法的项目生成文档。它允许我们大量自定义所有内容，例如指定参数、错误代码、响应示例等。网址为http://apidocjs.com/

JavaScript 项目文档的优秀示例

创作新作品时，最好能有一些可以参考的例子。所以，这里列出了一些你可以从中获得灵感的项目。它们都很棒，所以选择一个你最喜欢的吧。

• Firebase
• React Admin 模板（我们自己的一个项目的文档。我们花了大约 250 个小时编写这些文档）；
• 布格斯纳格
• Ruby on Rails 指南
• CatBoost

概括

我希望这篇文章对你有所帮助，并希望它能帮助你为你的 JavaScript 项目创建文档。通过谷歌搜索，我发现文档是任何 JavaScript 项目成功的关键，我非常赞同这条规则。文档就像一个门面，人们在使用你的项目时会面对它并依赖它。所以，请始终保持文档更新，并设身处地为用户着想！

最初发布于flatlogic.com — React、Angular、Vue、Bootstrap 和 React Native 模板和主题。

文本来源：https ://flatlogic.com/blog/writing-documentation-for-your-javascript-project/