写作样式指南¶

主要目标¶

本手册的主要目标如下：

用户聚焦: 本手册是为受过计算机图形学教育，能理解三维基础知识和/或了解其他三维软件的用户编写的。尽管计算机图形学的某些领域属于高深技术，但是本手册需要对于非技术用户是可以理解的。
完备: 该手册提供了 Blender 中所有功能、工具和选项的详细功能说明。虽然 Blender 的每个关键领域都有规范的理论根据，但这并不意味着我们必须记录每一个细枝末节。手册应提供有关功能是什么、如何使用功能及其用途的信息。必要时应提供更多背景信息，以便更深入地了解 3D 管道。
简洁: 计算机图形学是一个非常有趣的领域，其中有许多规则、规则的例外情况和有趣的细节。然而，扩展到细节可能会添加不必要的内容；因此，请保持文字简洁并与最终用户相关。
可维护: 请记住，Blender 的发布频率很高，因此在编写内容时，尽量不要一有小改动就重做。这也有助于小型文档社区维护手册。

内容指南¶

为了在手册中保持一致的书写风格，请记住此页面，只有在您有充分理由这样做时才会偏离此页面。

经验法则：

强烈推荐拼写检查。
使用美式英语（比如：modeling 而不是 modelling，color 而非 colour），数字格式化也一样（比如：2,718.28 而非 2 718,28）。
注意语法，合理用词并使用简单英语。
句子要简短清晰。
解释一个选项为什么或者如何有用是一个好主意。
如果你不能确定如何一个功能的工作原理，问别人，或找出开发者并提问。

要避免：

避免以第一人称视角写作，避免描写自己或自己的观点。
避免使用模棱两可的用词与不必要的含糊，例如：

“重新加载文件也许可以解决这个问题”

“大多数人不会使用此选项，因为 ...”
避免包含具体细节如：

“Blender 有 23 种不同的修改器。”

“启用预览会使每个 blend 文件大小增大 65536 字节（除非被压缩）。”

这些详细信息对用户没有用处，并且很快就会过时。
避免记录 bug。

Blender 每次发布都会修复数百个错误，因此不能指望手册能跟上。

开发人员已知且在下一版本之前不会解决的问题可以记录为 已知限制。在某些情况下，最好将它们包含在故障排除章节中。
避免产品植入，比如不必要地推广软件或硬件品牌。尽可能保持内容的中立性。
对一个功能，如果有简单的解释方法，避免使用其数学/算法实现的技术解释。

（比如，解释网格平滑算法原理就没必要，但是混合节点的混合类型确实需要数学解释。）
避免大段文字重复。只需解释一次，之后引用该解释即可。

对于通用术语，考虑在词汇表中定义 :term:。
避免在菜单中列出每个选项，例如帧速率。

选项内容可以概述或者简单略过。——这些列表仅显示界面中已经明显不过的内容，最终需要阅读和维护大量文本。
避免记录 Blender 相邻版本间的变化，这些都在发行说明里。我们仅需要记录 Blender 目前的状态。
除非用来衡量一个数值的单位鲜为人知且不可预料，否则没有必要提及。
不要简单地复制 Blender 的工具提示。——读者阅读手册是为了学到更多 UI 之外的东西。

万不得已的话，可以添加注释（不会显示在 HTML 页面，但是可以帮到其他编辑人员）:
```
.. TODO, how does this tool work? ask Joe Blogg's.
```

词汇表¶

这部分特别针对词汇表部分，该部分用于定义 Blender 和计算机图形学中的通用术语。

经验法则：

在提供进一步的信息之前，先定义术语。
定义前避免使用如 "it is" 或者 "xyz is" 的结构。
避免立即重复所述术语或在定义中使用它。
避免添加在 Blender 的界面或手册中用不到的术语。
避免过长的条目。如果有一个复杂的术语需要解释，可以补充外部链接。
避免复制文档；如果手册另一章节的主要焦点就是解释这个术语（例如，如果该术语是某个工具的名称），要么直接链接该章节，或者避免新建一个全新的词汇条目。

URL 引用写在最后，格式如下:

See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.

示例¶

该条目:

Displacement Mapping
   Uses a grayscale heightmap, like Bump Mapping,
   but the image is used to physically move the vertices of the mesh at render time.
   This is of course only useful if the mesh has large amounts of vertices.

可以这样写，先给出定义:

Displacement Mapping
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have enough geometry.

该条目:

Doppler Effect
   The Doppler effect is the change in pitch that occurs
   when a sound has a velocity relative to the listener.

可以这样写，避免立即重复术语:

Doppler Effect
   Perceived change in pitch that occurs
   when the source of a sound is moving relative to the listener.

该条目:

Curve
   It is a class of objects.
   In Blender there are Bézier curves and NURBS curves.

可以这样写，避免使用 "it is":

Curve
   A line interpolated between Control Vertices.
   Common types include Bézier and NURBS.