内容规范

本文档概述了官方文档中应当包含的内容。你可以在下面找到一些关于如何编写简单易懂的内容的原则和建议。

我们想实现两个目标：

  1. 与用户共情。写作时，应该让通过文档来学习变得简单。

  2. Write a complete reference manual. Our goal here is not to teach programming fundamentals. Instead, our goal is to provide a reference for how Godot’s features work.

规范与原则

Below are the guidelines we should strive to follow. They are not hard rules, though: sometimes, a topic will require breaking one or more of them. Still, we should strive to achieve the two goals listed above.

编写完善易懂的文档

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

备注

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

Do your best to keep documents under 1000 words in length. If a page goes past that threshold, consider splitting it into two parts. Limiting page size forces us to write concisely and to break up large documents so that each page focuses on a particular problem.

Each page or section of a page should clearly state what problem it tackles and what it will teach the user. Users need to know if they’re reading the correct guide for solving the problems they’re encountering. For example, instead of writing the heading “Signals”, consider writing “Reacting to changes with signals”. The second title makes it clear what the purpose of signals is.

备注

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

如果某个页面假设读者了解引擎的另一项功能，请在开头给出相关介绍以及能够为用户提供必要信息的文档链接。例如，一个涉及到物理处理的页面可能使用了信号（Signals）功能，在这种情况下你会注意到关于信号的教程是一种前置要求。在给出相关 Godot 文档链接的同时你也同样可以列出来自其他网站的链接。例如，你可以在入门指南中给出编程介绍的章节链接，或者是在数学运算部分给出教授对应数学理论的网站链接。

减少认知负担

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

  1. 尽可能一次只介绍一个新概念。

  2. 就像在编写规范中推荐的一样，使用简单的英语。

  3. Including one or more concrete usage examples. Prefer a real-world example to one that uses names like foo, bar, or baz.

尽管许多人能够理解复杂的语言和抽象的例子，但还是会有其他一些人理解不了。而通俗易懂的写作方式和实际的例子则能让所有人都受益。

Always make an effort to put yourself in the user’s shoes. When we understand something thoroughly, it becomes obvious to us. We may fail to think about details relevant to a newcomer, but good documentation meets users where they are. We should explain each feature’s capabilities or intended uses with the most straightforward language possible.

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

备注

拥有编程基础是使用像 Godot 这样复杂引擎的前提条件。讨论变量、函数、类是可以接受的，但相对于“元编程”之类的特定术语，我们应该更倾向于使用通俗易懂的语言来表达它们。如果你需要使用精准的术语，请务必通过定义解释它们。