如果您最近访问过angular.io的文档，您可能会注意到我们的内容布局和结构发生了一些变化。作为 Angular 的首席技术作家，我想花点时间来介绍一下我们的一些主要目标，以使 Angular 文档体验成为可能的最佳体验。

关注刚接触 Angular 的开发人员

许多文档集的一个常见陷阱是它们同时面向太多受众。这种做法会导致内容冗长、难以导航且难以阅读。对于 Angular 来说，一次只关注一个受众非常重要，因为我们希望确保清晰简洁地讲述正确的故事。目前，这意味着我们的文档工作主要针对刚接触 Angular 的开发人员。

自从加入 Angular 团队以来，我经常听到一个主题：

“Angular 的学习曲线很陡峭。”

“Angular 文档非常丰富。”

作为 Angular 的新手，我发现自己同意这些观点。这就是为什么在接下来的几个月里，我们致力于让入门体验尽可能成为最佳体验。我们正在做出的一些改变包括：

• 修改目录（左侧导航中的主题列表）以帮助用户了解他们应该了解的 Angular 的主要概念，以及哪些主题可以等到他们想要进一步扩展其应用程序时再了解。
• 将主题分为三种主题类型：概念、任务和教程。这对于任何读者都很重要——无论他们是否是 Angular 的新手！ – 了解他们正在阅读什么类型的内容以及这是否是他们正在寻找的内容。没有人喜欢寻找如何完成某件事，却发现自己只在教程中找到了 3 段内容。
• 精简现有内容。当我写作时，我想象我正在辅导一位 5 分钟后要赶飞机的朋友。这张图片帮助我专注于语气随意但又简洁明了的内容。将这个想法应用到 Angular 文档中将帮助用户找到他们需要的信息并返回代码。

帮助用户完成工作

开发人员出于多种不同的原因需要文档。有时您需要对该技术进行基本演练。其他时候，您需要一个现实世界的教程来解决您面临的问题。就像关注特定受众一样，一套好的文档集每次都会关注其中一个原因。对于 Angular，我们专注于编写帮助用户完成工作的内容。

当您导航到 Angular 文档时，我们希望您找到完成任务或理解功能所需的信息，然后我们希望您能够重新编写出色的代码。为了实现这一目标，我们将仔细研究所有主题，以确保它们清楚地说明所涵盖的内容以及其重要性。您应该立即知道您是否正在阅读所需的内容。如果你不是？我们正在努力提供可能更有帮助的其他主题的链接。

当然，总有一个地方可以容纳更多概念性内容。深入了解事物的工作原理具有很大的价值。我确信我们会在未来的某个时候专注于改进我们的概念内容。不过，目前我们希望确保您能够快速轻松地找到所需的帮助。

改进，但不要破坏

正如我们之前提到的，Angular 社区中的许多人发现当前的文档令人不知所措。同时，我们还听说文档仍然是学习如何使用 Angular 进行构建的最佳位置之一。这就是为什么我们关注的其他关键目标之一是在不破坏文档的情况下改进文档。当我们编写新内容或改进现有内容时，我们会尽力确保现有文档保持完整。有时我们可能会达不到这个目标。发生这种情况时，请通过提交GitHub 问题告知我们，以便我们进行调查。

结论

我们认为，专注于新的 Angular 开发人员，编写有助于您完成工作的内容，并确保我们在不破坏文档的情况下改进文档，将为每个人带来更好的文档体验。当然，这只是一个开始。例如，当我们为新开发人员总结内容时，我们将开始关注其他受众，例如那些从事企业级应用程序工作的受众。我无法表达我对开发一个拥有如此充满热情、支持性社区的产品的感激之情，我期待着与你们所有人合作，使 Angular 文档成为可能的最佳体验。与此同时，请继续查看文档，并随时告诉我们您的想法！

文章来源地址：https://blog.angular.dev/angular-thoughts-on-docs-74dd343039c0