Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

内容规范

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

我们想实现两个目标：

  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.

备注

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

If the page assumes specific knowledge of other Godot features, mention it and link to the corresponding documentation. For instance, a page about physics may use signals, in which case you could note that the signals tutorial is a prerequisite. You may also link to other websites for prerequisites beyond the documentation's scope. For example, you could link to an introduction to programming in the getting started guide, or a website that teaches math theory in the math section.

减少认知负担

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

  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.

While many people may understand more complex language and abstract examples, you will lose others. Understandable writing and practical examples benefit everyone.

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.

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

备注

Programming fundamentals are a prerequisite for using a complex engine like Godot. Talking about variables, functions, or classes is acceptable. But we should favor plain language over specific terminology like "metaprogramming". If you need to use precise terms, be sure to define them.