内容规范

本文档致力于帮助大家评估哪些内容应该加入到官方文档中。你可以在下面找到一些关于如何编写简单易懂的内容的原则和建议。

我们想实现两个目标：

规范与原则

以下是我们应该努力遵守的规范。不过这些并不是硬性规定：特殊情况下，某个主题会需要打破这里的若干规范。不过我们还是应该尽量完成上面所列出的两个目标。

功能在编写文档前是不存在的。如果用户无法找到某个功能的信息和用法，那么这个功能对于他们就不存在。我们应该保证涉及到 Godot 的方方面面。

备注

添加或更新引擎的功能时，文档团队应该跟进。工作成果被合并后，如果需要文档，贡献者应该在 godot-docs 仓库创建 Issue。

请竭尽所能将文档保持在1000 个单词以内。如果页面超过了这个阈值，如果可能，请考虑将它拆分成两个部分。对页面的大小作出限制，强制我们在写作时保持简洁，将大段的文档进行拆分可以让每一部分都集中于某个特定的问题。

讲清楚每个页面或章节所针对的问题，以及用户会学到什么。用户需要知道他们看的指南是否能够正确解决他们所遇到的问题。例如，请不要在题目里写“Signals”（信号），请考虑写“Reacting to changes with signals”（使用信号对变化作出响应）。后者标明了使用信号的目的。

备注

章节标题太长，侧边菜单的项目就会变长，导航也会变得冗长。请尽量让题目保持在五个单词以内。

如果页面中要用到其他 Godot 特性，请进行提及并链接到对应的文档。例如，关于物理的页面可能会用到信号，那么就可以标明介绍信号的页面是该页面的先决条件。

减少阅读文档的认知负担。我们使用的语言越简单明了，大家学习起来效率就越高。你可以：

虽然很多人能够理解复杂的语言和抽象的例子，你还是会失去其他人。而且，通俗易懂的写作和实际的例子能让所有人都受益。

始终努力设身处地为用户着想。某件事情如果我们完全理解，对于我们而言就会变得显而易见。我们可能无法想象新手相关的细节，但好的文档就是要为用户雪中送炭。我们应该用尽可能直白的语言，尽力去解释每一个特性的用处或用法。

回想一下学习某个功能或概念时，你首先需要了解的东西。你需要用到哪些新的术语？你困惑的点是什么？最难掌握的是什么？你会希望让用户对你的成果进行评审，我们建议你在着手写作之前，先练习一下如何解释这个功能。

备注

拥有编程基础是使用像 Godot 这样复杂的引擎的先决条件。你可以用到变量、函数、类。不过相对于“元编程”之类的特定术语，我们应该更倾向于使用平实的语言。如果你需要使用精准的术语，请一定要给出定义。

如果某个页面假设读者了解引擎的另一项功能，请在开头给出介绍和能够为用户提供必要信息的资源链接。如果先决条件不在文档的范畴内，你也可以链接到其他网站。例如在数学章节中，你可以链接到入门指南中的编程简介章节，也可以链接到某个教授数学理论的网站。