写作样式指南

主要目标

本手册的主要目标如下。

用户聚焦

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

完备

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

简洁

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

可维护

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

内容指南

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

经验法则：

  • 强烈 推荐拼写检查。

  • 使用美式英语(比如: modeling而不是modelling, color而非 colour)，数字格式化也一样 (比如: 2,718.28 而非 2 718,28)。

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

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

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

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

要避免：

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

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

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

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

  • 避免包含具体细节如:

    “Bleder有23中不同的修改器”

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

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

  • 避免记录bug。

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

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

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

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

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

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

    对于通用术语，考虑在 词汇表 中定义 :term: 。

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

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

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

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

  • 不要简单地复制Blender的工具提示。——读者阅读手册是为了学到 更多 UI之外的东西。

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

    1. .. TODO, how does this tool work? ask Joe Blogg's.

词汇表

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

经验法则：

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

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

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

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

  • 避免过长的条目。如果有一个复杂的术语需要解释，可以补充外部链接。

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

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

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

示例

该条目:

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

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

  1. Displacement Mapping
  2.    A method for distorting vertices based on an image.
  3.    Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
  4.    This relies on the mesh having enough geometry.

该条目:

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

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

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

该条目:

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

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

  1. Curve
  2.    A type of object defined in terms of a line interpolated between Control Vertices.
  3.    Available types of curves include Bézier and NURBS.