新的一年的开始是回顾我们在 Angular 文档方面所做的一些工作的好机会。我发现这些反思机会很有帮助；它们让我能够真正审视我们已经取得的成就、我们未能实现的目标以及我们下一步应该关注的重点。通常，我会自己进行这些反思；这次，我想与社区分享我的想法。

我们第四季度的重点

正如我们最近的调查所示，Angular 社区非常重视文档。

当我加入 Angular 团队时，我的首要任务之一是确定文档的哪些领域最需要改进。当我听取产品团队和社区的意见时，有一点很突出：我们需要更好地向开发人员介绍 Angular。因此，当我们开始第四季度的工作时，我们决定重点关注 Angular 框架的新开发人员。这一决定使我们将重点放在我们认为对受众最重要的内容上，例如“入门”部分。我们还重点关注我们认为对那些考虑或刚刚开始 Angular 之旅的人最有影响力的内容，例如我们关于组件、模板、指令和依赖注入的内容。

编辑、编辑、更多编辑

作为这一重点的一部分，我们花费了大量时间编辑现有内容。我们的编辑过程不仅仅是修复印刷和语法错误。我们彻底检查了每个主题，审查内容是否相关，如果相关，这些想法是否清晰、简洁和完整地传达。我们将大而繁重的主题分成更小、更易于管理的部分。我们检查了如何传达想法，以确保在可以使用 10 个单词的情况下我们不会使用 20 个单词。最重要的是，我们在发现重复内容时将其删除，并建立了一个系统来归档我们认为可能过时的内容。如果您查看“入门”和“理解 Angular”部分中的内容，您应该会发现这些内容更容易阅读。

可扩展的信息架构

我们可以帮助新开发人员的另一种方法是拥有可扩展的信息架构。我们的结构有两个目标：首先，它必须帮助开发人员快速轻松地找到他们需要的信息。其次，它必须是可扩展的，这样，当我们随着时间的推移添加更多内容时，就可以很容易地确定新内容所属的位置。我们与 Angular 工程师合作，创建了文档的三个内容部分：

• 入门，重点向开发人员介绍 Angular 并为他们提供各种方法来决定 Angular 框架是否适合他们。
• 了解 Angular ，它提供了关键 Angular 概念的高级概述，例如组件、模板、指令和依赖项注入。
• 开发人员指南，提供有关 Angular 的许多不同特性和功能的深入文档，包括组件和模板的更高级用例、Angular 的路由器和表单包等内置功能等。

需要明确的是，创建这些部分只是一个开始。目标是帮助确保开发人员知道在哪里可以找到他们需要的信息，并且我们可以轻松地确定新内容在编写时应该放在哪里。这个新架构是一个伟大的第一步，但我们将继续听取社区的意见，以帮助确保开发人员能够在需要时找到他们需要的内容。

接下来怎么办？

阅读本文的许多人现在可能会认为，虽然这些更改可能看起来很有帮助，但它们并不真正适用于那些已经是经验丰富的 Angular 开发人员的人。我们从您那里了解到，Angular 有许多特性和功能我们没有完整记录或根本没有记录。

因此，在 2021 年第一季度，我们将把重点转向创建和改进以下领域的文档：

• Change detection 变化检测
• Zones 区域
• Performance 表现
• Content projection 内容投影

这些内容更新应该有助于解决 Angular 开发人员需要更多信息的一些主要领域。

最后一件事

我想用最后一项——也许是最重要的一项——来结束这篇文章。

处理像 Angular 文档这样的项目对任何技术作家来说都是一个重大挑战。范围如此之广，现有内容似乎无穷无尽，需要花费大量时间来弄清楚需要添加哪些内容、需要更新哪些内容以及不再需要哪些内容。如果没有你们这些 Angular 社区的杰出成员，这个项目就不可能取得进展。无论您是我们现有文档的支持者，还是在我们的文档不足时提出合理批评的人，你们都提供了建设性的反馈并支持编写团队的努力。因此，请允许我以感谢来结束这篇文章。感谢您分享您的想法、意见、建议和见解。优秀的文档需要协作努力，我期待着在来年聆听更多人的意见并与他们合作。

文章来源地址：https://blog.angular.dev/angular-thoughts-on-docs-looking-back-looking-ahead-228352cc72f2