文档编写指南

Godot社区富有而国际化。用户来自世界各地。他们中的一些人很年轻,许多人不是英语母语者。这就是为什么我们都必须用一种清晰而通用的语言来写作。对于课堂参考,目标是让每个人都能轻松、准确地阅读。

总之,始终尝试:

  1. 使用直接的声音

  2. 使用精确的动作动词

  3. 避免以ing结尾的动词

  4. 去掉不必要的副词和形容词。

  5. 禁止这8个词:明显的、简单的、基本的、简单的、实际的、公正的、清晰的,然而

  6. 使用显式引用

  7. 用“s”表示拥有

  8. 使用牛津逗号

描述类有三条规则:

  1. 在简要描述中概述节点

  2. 如果有用,请说明返回的方法

  3. 使用“if true”来描述布尔值

注解

技术作家的工作是尽可能将尽可能多的信息打包成尽可能小而清晰的句子。这些指导方针将帮助你朝着这个目标努力。

7.清晰英语规则

使用直接的声音

尽可能使用直接语音。以你描述的类、方法和常量为主题。使用被动语态写作是很自然的,但很难阅读并产生更长的句子。

被动:

The man **was bitten** by the dog.

活动:

The dog bit the man.

不要 使用被动语态:

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

Do 将节点的名称用作名词:

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

使用精确的动作动词

喜欢精确但普通的动词而不是一般的 makeset ,以及可以用单个单词替换的任何表达式。

不要 重复该方法的名称。它已经声明将透视值设置为新值:

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

Do 解释这个“集合”的结果是什么:使用精确的动词如 placepositionrotatefade 等。

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

避免以ing结尾的动词

进步的形式描述了连续的行动。例如,“正在呼叫”,“正在移动”。

不要 使用渐进形式进行即时更改。

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

Do 使用简单的现在、之前或未来。

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

你可以用进行时态来描述连续的动作。任何像动画或协同工作。

小技巧

动词可以变成形容名词。这不是连词,所以你可以用它们: the remaining movementthe missing file 等。

去掉不必要的副词和形容词

尽量少写形容词和副词。只有在描述中添加关键信息时才使用它们。

不要 使用多余或无意义的副词。延长文档但不添加任何信息的单词:

**Basically** a big texture [...]

Do 用简单的描述性语言写短句:

A big texture [...]

禁止这8个字

不要 曾经使用过这8个禁用词:

  1. 明显的

  2. 简单的

  3. 基本的

  4. 容易的

  5. 实际的

  6. 只是

  7. 清楚的

  8. 然而(一些用途)

游戏的创建和编程并不简单,对于第一次学习使用API的人来说,没有什么是容易的。列表中的其他单词,比如 justactual 不会在句子中添加任何信息。也不要使用相应的副词:显然,简单,基本,简单,实际上,清晰。

不要 例子。禁止使用的词语会延长描述的长度,并将注意力从最重要的信息上移开:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

Do 删除它们:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

“简单”从来没有帮助。请记住,对于其他用户来说,任何事情都可能是复杂的或使他们沮丧的。没有什么比得上一个好老人 这很简单 让你畏缩。下面是老的简要描述,计时器节点页面上的第一句话:

**Timer**
A **simple** Timer node.

Do 解释节点的作用:

**Timer**
Calls a function of your choice after a certain duration.

不要 使用“基本”,太模糊了:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

Do 使用简要描述提供节点的概述:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

使用显式引用

支持显式引用而不是隐式引用。

不要 使用“前一个”、“后一个”等词。它们在英语中不是最常见的,它们要求您检查参考文献。

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

Do 重复单词。它们消除了所有的歧义:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

如果您需要重复相同的变量名3或4次,您可能需要重新表述您的描述。

用“s”表示拥有

避免“牛奶” of 奶牛”。在英语里这感觉不自然。改为写“牛奶”。

不要 写“of the X”:

The region **of the AtlasTexture that is** used.

Do 使用 's . 它可以让你把主语放在句子的开头,并保持简短:

The **AtlasTexture's** used region.

用牛津逗号来列举任何东西

摘自《牛津词典》:

“Oxford逗号”是一个可选的逗号,位于列表末尾的单词“and”之前: 我们卖书、视频和杂志。

[...] 并非所有的作者和出版商都使用它,但当列表中的项目不是单个单词时,它可以澄清句子的含义: 这些商品有黑色和白色,红色和黄色,蓝色和绿色。

不要 将列表的最后一个元素保留为不带逗号:

Create a KinematicBody2D node, a CollisionShape2D node and a sprite node.

Do 在前面加逗号 andor ,对于包含两个以上元素的列表的最后一个元素。

Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node.

如何编写方法和类

在简要描述中概述节点

简短的描述是参考文献中最重要的一句话。这是用户与节点的第一次联系:

  1. 这是“创建新节点”对话框中唯一的描述。

  2. 在参考资料的每一页的顶部

简要描述应该用200个字符来解释节点的角色及其功能。

不要 写一些小而模糊的总结:

**Node2D**
Base node for 2D system.

Do 概述节点的功能:

**Node2D**
2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.

使用节点的完整描述来提供更多信息,如果可能,还可以使用代码示例。

如果有用,请说明返回的方法

有些方法返回重要值。在描述的末尾描述它们,最好是在新行上。无需提及名称以开头的任何方法的返回值 setget .

不要 使用被动语态:

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

Do 始终使用“退货”。

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

注意“直接语音”规则的例外情况:使用move方法,外部碰撞器可以影响调用的方法和主体 move . 在这种情况下,您可以使用被动语态。

使用“if true”来描述布尔值

对于布尔成员变量,始终使用 if true 和/或 if false ,保持明确。 Controls whether or not 可能不明确,不能对每个成员变量都有效。

还将布尔值、变量名和方法用 [code][/code] .

Do 从“如果为真”开始:

Timer.autostart
If [code]true[/code] the timer will automatically start when it enters the scene tree. Default value: [code]false[/code].

使用 [code] 围绕论点

在类引用中,总是用 [code][/code] . 在文档和godot中,它将显示为 this . 在godot存储库中编辑XML文件时,请将类似“this”或“this”的现有参数替换为 [code]this[/code] .

Godot文献中常用词汇

开发人员选择了一些特定的词来引用接口的区域。它们被用于源代码和文档中,您应该始终使用它们而不是同义词,这样用户就知道您在说什么了。

Overview of the interface and common vocabulary

界面和常用词汇概述

在编辑器的左上角 main menus . 在中间,按钮改变 workspace . 右上角的按钮是 playtest buttons . 显示二维或三维空间的中心区域是 viewport . 在顶部,您可以找到 tools 里面 toolbar .

视区任一侧的选项卡或可停靠面板是 docks . 你有 FileSystem dock , the Scene dock 包含你的场景树, Import dock , the Node dockInspectorInspector dock . 使用默认布局,您可以调用选项卡式码头 tabsScene tab , the Node tab

在视区底部的动画、调试器等是 panels . 他们一起组成了 bottom panels .

检查员的可折叠区域为 sections . 节点的父类名称(不能折叠)是 Classes 例如 KinematicBody2D class . 带有键值对的单个行是 properties . 例如。 positionmodulate color 都是 properties .

图像贡献准则

文档的一个重要部分是图像,需要遵循几个重要的指导原则。

首先,在截屏时应该始终使用默认的编辑器主题和文本。

对于3D截图,使用4xmsaa,在项目纹理上启用各向异性过滤,并在项目设置中将各向异性过滤质量设置为16x。

屏幕截图大小不应超过1920x1080。

当需要突出显示编辑器的某个区域以显示某些内容(如按钮或选项)时,请使用不带斜角的2像素厚轮廓。

在添加或替换文档中的任何图像之前,应该通过PNG压缩程序运行它们以节省大小。内置无损压缩程序,如krita或photoshop应该完成。但是,您也应该使用有损的,例如 pngquant 在压缩过程中几乎没有图像质量损失。