写作样式指南

主要目标

本手册的主要目标如下：

用户聚焦

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

完备

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

简洁

Computer graphics is an incredibly interesting field, there are many rules, exceptions to the rules, and interesting details. Expanding into details can add unnecessary content, so keep the text concise and relevant to the topic at hand.

可维护

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

内容指南

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

经验法则：

  • 强烈 推荐拼写检查。

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

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

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

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

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

要避免：

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

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

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

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

  • 避免包含具体细节如:

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

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

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

  • 避免记录bug。

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

    Issues that are known to the developers and are not going to be resolved before the next release can be documented as Known Limitations. In some cases, it may be best to include them in the troubleshooting section.

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

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

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

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

    对于通用术语，考虑在 词汇表 中定义 :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.