写作样式指南

用户聚焦

虽然计算机图形学某些领域技术性很高，本手册尽量确保非技术用户能够理解。

完备

因此，Blender的每个关键领域都有规范的真实来源。 这并不意味着我们必须记录每一个细节，但用户不必依赖于在别处搜索以找到关键特性的用意。

简洁

计算机图形学是一个令人无比有趣的领域，有许多规则，规则的例外和有趣的细节。谈到细节会增加不必要的内容，所以保持文字简洁，与话题相关性。

可维护

记住Blender更新频繁，所以尽量保证所写内容不会因为一些小的修改而重写。这也有助于小型文档社区维护手册。

内容指南

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

经验法则：

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

要避免：

• 避免使用第一人称视角描写，关于自己或自己的意见。

• 避免使用 与不必要的含糊, 例如:

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

  “大多数人不会使用此选项，因为 …”

• 避免记录bug。

  Blender 相邻版本之间通常会修复100个左右的bug, 所以在手册中提到这些，再去不断更新bug列表，并没有实际意义。

  开发者已知，且在下一个版本发布前无法解决的问题，可以记录为 已知局限 。在一些情况下，最好将它们写到 问题排查 部分。

• 避免产品植入，即不必要的软件或硬件品牌推广。尽量保持内容的厂商中立原则。

• 对一个功能，如果有简单的解释方法，避免使用其数学/算法实现的技术解释。

  (比如，解释网格平滑算法原理就没必要， 但是混合节点的混合类型确实需要数学解释)

• 避免大段文字重复。只需解释一次，之后引用该解释即可。

  对于通用术语，考虑在 中定义 。

• 避免类似选项的枚举，比如列出选择菜单中的每一个预设值或者每一个帧率。

  选项内容可以概述或者简单略过。——这些列表仅显示界面中已经 明显 不过的内容，最终需要阅读和维护大量文本。

• 避免记录Blender相邻版本间的变化，这些都在发行说明里。我们仅需要记录Blender目前的状态。

• 除非用来衡量一个数值的单位鲜为人知且不可预料，否则没有必要提及。

• 万不得已的话，可以添加注释(不会显示在HTML页面，但是可以帮到其他编辑人员):

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

经验法则：

• 在提供进一步的信息之前，先定义术语。

• 定义前避免使用如“it is”或者“xyz is”的结构。

• 避免立即重复所述术语或在定义中使用它。

• 避免添加在Blender的界面或手册中用不到的术语。

• 避免复制文档；如果手册另一章节的主要焦点就是解释这个术语(例如，如果该术语是某个工具的名称)，要么直接链接该章节，或者避免新建一个全新的词汇条目。

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

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

示例

该条目:

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

Displacement Mapping
   A method for distorting vertices based on an image.
   This relies on the mesh having enough geometry.

该条目:

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

Doppler Effect
   Perceived change in pitch that occurs

该条目:

Curve
   A type of object defined in terms of a line interpolated between Control Vertices.