写作样式指南

主要目标

本手册的主要目标如下：

用户聚焦

本手册是为受过计算机图形学教育，能理解三维基础知识和/或了解其他三维软件的用户编写的。尽管计算机图形学的某些领域属于高深技术，但是本手册需要对于非技术用户是可以理解的。

完备

该手册提供了 Blender 中所有功能、工具和选项的详细功能说明。虽然 Blender 的每个关键领域都有规范的理论根据，但这并不意味着我们必须记录每一个细枝末节。手册应提供有关功能是什么、如何使用功能及其用途的信息。必要时应提供更多背景信息，以便更深入地了解 3D 管道。

简洁

计算机图形学是一个非常有趣的领域，有许多规则，规则的例外和有趣的细节。扩展到细节可能会添加不必要的内容，因此请保持文本简洁且与手头的主题相关。

可维护

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

内容指南

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

经验法则：

  • 强烈 推荐拼写检查。

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

  • 注意语法，合理用词并使用简单英语。

  • 保持句子简短清晰，可使文字易于阅读，客观和中肯。

  • 解释一个选项为什么或者如何有用是一个好主意。

  • 如果你不能确定如何一个功能的工作原理，问别人，或找出开发者并提问。

要避免：

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

  • 避免使用模棱两可的用词与不必要的含糊，例如：

    重新加载文件也许可以解决这个问题
    大多数人不会使用此选项，因为 ...

  • 避免包含具体细节如:

    Blender 有 23 种不同的修改器。
    启用预览会使每个 blend 文件大小增大 65536 字节（除非被压缩）。

    用户记住这些细节毫无用处，并且会很快过时。

  • 避免记录 bug。

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

    开发人员已知且在下一版本之前不会解决的问题可以记录为 已知限制。在某些情况下，最好将它们包含在故障排除章节中。

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

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

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

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

    对于通用术语，考虑在词汇表中定义 :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
   A method for distorting vertices based on an image.
   Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
   This relies on the mesh having 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 type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.