Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

内容指南

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

我们想实现两个目标：

理解用户并与之共情。我们应该使用一种方式来编写文档，使得用户能够易于从其中学习。
编写一个完整的参考手册。我们在这的目标不是教授基础的编程知识，相反，我们的目标是为如何使用 Godot 一系列的功能来提供参考资料。

指南与守则

以下是我们应该努力遵循的指南。不过，它们并不是硬性规定：有时，某个主题会需要打破这里的若干准则。尽管如此，我们还是应该尽力达到上面所列出的两个目标。

编写完善易懂的文档

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

备注

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

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

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

备注

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

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

减少认知负担

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

尽可能一次只介绍一个新概念。
就像在编写指南中推荐的一样，使用简单的英语。
提供一个或多个具体使用示例。使用真实世界的例子比使用像 foo, bar, baz 这样的抽象占位符更好让人理解。

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

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

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

备注

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