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

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

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

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

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

Полнота

В руководстве представлено подробное функциональное описание всех функций, инструментов и опций Blender. Хотя для каждой из ключевых областей Blender существует канонический источник истины, это не означает, что мы должны документировать каждую мелочь. В руководстве должна быть представлена информация о том, что представляет собой функция, как её использовать и её назначение. При необходимости необходимо предоставить дополнительную справочную информацию для более глубокого понимания 3D-конвейера.

Краткость

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

Удобный в сопровождении

Помните, что выпуски Blender выходят довольно часто, так что старайтесь писать так, чтобы потом не пришлось всё переписывать из-за одного незначительного изменения. Также это поможет поддерживать руководство небольшому сообществу документаторов.

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

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

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

  • Проверка орфографии – строго рекомендуется.

  • Use American English (e.g: modeling and not modeling, 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).» («Включение предпросмотра добавляет 65536 байт к размеру каждого blend-файла (если он не сжат).»)

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

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

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

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

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

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

    (Например, нет необходимости объяснять, как работают алгоритмы сглаживания меша, но типы смешивания ноды «Mix» требуют математического объяснения.)

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

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

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

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

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

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

  • Не надо просто копировать всплывающие подсказки из Blender. – Люди будут обращаться к руководству, чтобы узнать больше, чем предоставляет пользовательский интерфейс.

    В качестве последней меры вы можете добавить комментарий (который не будет показываться на 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.