Attention: Here be dragons
This is the
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
This document outlines what should be included in the official documentation. Below, you will find a couple of principles and recommendations for writing accessible content.
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.
Including one or more concrete usage examples. Prefer a real-world example to one that uses names like
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.