Руководство по стилю написания

Основные цели

Ниже перечислены основные цели данного руководства.

Ориентированность на пользователя

Хотя некоторые области компьютерной графики изобилуют техническими терминами, это руководство должно быть понятным и пользователям без технического образования.

Полнота

Руководство должно быть каноническим источником истины в последней инстанции для каждой ключевой области Blender. Это не значит, что мы должны документировать каждую незначительную деталь, однако пользователи не должны полагаться на поиск информации где-нибудь в других местах, чтобы узнать о ключевых возможностях продукта.

Краткость

Компьютерная графика - это невероятно интересная область, в ней есть много правил, исключений из правил и интересных деталей. Углубившись в подробности, можно добавить ненужное содержимое, поэтому сохраняйте текст кратким и не сбивайтесь с заданной темы.

Поддерживаемость

Помните, что выпуски 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).

  • Позаботьтесь о грамматике, соответствующих формулировках и используйте простой английский язык.

  • Составляйте предложения краткими и ясными, чтобы результирующий текст было легко читать, он был объективным и точно выражал суть.

  • Хорошей идеей будет включить описание того, почему или как какой-нибудь параметр может быть полезен в работе.

  • Если вы не знаете, как работает определённая функция, спросите кого-нибудь ещё или найдите её разработчика и спросите у него.

Чего следует избегать:

  • Избегайте написания от первого лица, о себе или выражения своего мнения.

  • Избегайте анонимных авторитетов и излишне расплывчатых формулировок, к примеру:

    «Reloading the file will probably fix the problem» («Перезагрузка файла возможно исправит проблему»)
    «Most people do not use this option because …» («Большинство людей не используют этот параметр, поскольку…»)

  • Избегайте упоминания слишком подробных деталей, например:

    «Blender has 23 different kinds of modifiers.» («Blender содержит 23 различных вида модификаторов.»)
    «Enabling previews adds 65536 bytes to the size of each blend-file (unless it is compressed).»

    Эти подробности пользователям не нужно запоминать, да и они быстро могут устареть.

  • Избегайте документирования ошибок.

    В Blender зачастую между выпусками исправляется более сотни ошибок, так что даже на часть из них не реально сослаться из руководства, тем более поддерживать этот список в актуальном состоянии.

    Известные разработчикам замечания, которые явно не будут разрешены до следующей версии, могут быть задокументированы как известные ограничения, что в некоторых случаях может быть предпочтительнее включения их в раздел с решением известных проблем.

  • Avoid product placements, i.e. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

  • Избегайте технического описания реализации математики/алгоритма функции, если существует более простое объяснение.

    (E.g. explaining how mesh smoothing algorithms work is unnecessary, but the blending types of a Mix node do need a mathematical explanation.)

  • Избегайте повторения больших кусков текста. Давайте объяснение только в одном месте, а из других просто ссылайтесь на него.

    Если описание относится к общей терминологии, имеет смысл определить соответствующий термин (:term:) в словаре.

  • Avoid enumerations of similar options, such as listing every preset or every frame rate in a select menu.

    Их содержимое можно описать одним предложением или просто опустить. Такие списки показывают только то, что и так уже очевидно из интерфейса, они занимают много места и их тяжело читать и поддерживать.

  • Избегайте документирования изменений в Blender между его выпусками, для этого существуют примечания к выпуску. Необходимо документировать только текущее состояние Blender.

  • Если единица измерения измеряемого значения неясна и непредсказуема, нет необходимости говорить об этом.

  • Do not simply copy the tooltips from Blender. – People will come to the manual to learn more than is provided by the UI.

    В качестве последней меры вы можете добавить комментарий (который не будет показываться в HTML-странице, но будет полезным для других редакторов):

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

Словарь

This section is specifically about the Glossary section, where we define common terms in Blender and computer graphics.

Эмпирические правила:

  • Определяйте термин до предоставления любой другой связанной информации.

  • Avoid using constructs such as «it is» or «xyz is» before the definition.

  • Избегайте повторения термина в начале или в середине определения.

  • Избегайте добавления терминов, которые не упоминаются в интерфейсе 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.