Writing Style Guide – Путівник зі Стилю Написання#

Primary Goals – Первісні Цілі#

Головні цілі цього посібника наступні:

User Focused – Орієнтованість на Користувача

Цей посібник написаний для людей, що отримали освіту в галузі комп’ютерної графіки, котрі розуміють основи 3D та/або знають інше програмне забезпечення у сфері 3D. Хоча деякі області комп’ютерної графіки є високо технічними, цей посібник повинен бути зрозумілим для не-технічних користувачів.

Complete – Завершеність

Посібник надає детальний функціональний опис всіх функціональностей, засобів та опцій у Blender. Хоча існує канонічне джерело істини для кожної з ключових областей Blender’а, це не означає, що ми маємо документувати кожну дрібну деталь. Посібник повинен надавати інформацію про те, що таке певна функціональність, як її використовувати та яке її призначення. Більше базової інформації повинно надатися при необхідності дати глибше розуміння конвеєра у галузі 3D.

Concise – Стислість

Комп’ютерна графіка є неймовірно цікавою галуззю, де є багато правил, винятків із правил та цікавих деталей. Заглиблення в деталі може додавати непотрібний вміст, тому утримуйте текст стислим та відповідним безпосередньо темі.

Maintainable – Підтримуваність

Майте на увазі, що Blender має часті випуски, тому намагайтеся писати вміст, який не потрібно буде переробляти, коли вноситься якась дрібна зміна. Це також допомагає невеликій спільноті документації підтримувати цей посібник.

Content Guidelines – Настанови щодо Вмісту#

Щоб підтримувати узгоджений стиль писання у межах цього посібника, будь ласка, пам’ятайте написане на цій сторінці та тільки тоді відхиляйтеся від цього, коли є на те значна причина.

Емпіричні правила:

  • Перевірка правопису настійно рекомендується.

  • 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).

  • Турбуйтеся про граматику, відповідний підбір слів та використання простої Англійської.

  • Зберігайте речення короткими й зрозумілими, результатний текст легким для читання, об’єктивним і суттєвим.

  • Визначення того, чому і як та чи інша опція може бути корисною, – це добра ідея.

  • Якщо ви не впевнені у тому, як функція працює, спитайте когось ще або знайдіть того, хто її розробив та спитайте його.

Що слід уникати:

  • Уникайте писання від першої особи, про себе або про власні думки.

  • Уникайте обтічних слів weasel words та непотрібної розпливчастості, наприклад:

    «Перезавантаження файлу можливо вирішить проблему»
    «Більшість людей не використовують цю опцію, тому що …»

  • Уникайте включення специфічних деталей, таких як:

    «Blender має 23 різних типи модифікаторів.»
    «Вмикання передоглядів додає 65536 байтів до розміру кожного blend-файлу (допоки він не стискається).»

    Ці деталі не є корисними для користувачів для запам’ятовування і можуть швидко стати не актуальними.

  • Уникайте документування дефектів.

    Blender часто має сотні дефектів, які виправляються між випусками, а тому не реально посилатися навіть на частину з них у цьому довіднику, зберігаючи їх перелік актуальним.

    Проблеми, що відомі розробникам та не плануються вирішуватися до наступного випуску, можуть документуватися як відомі обмеження Known Limitations. У деяких випадках може найкраще включити їх у розділ про усунення несправностей – troubleshooting.

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

  • Уникайте технічних пояснень щодо математичної/алгоритмічної імплементації функціональності, якщо є простіший спосіб пояснити її.

    (Наприклад, пояснювання, як працюють алгоритми згладжування сіті, не є необхідним, а от типи змішування вузла Mix потребують математичного пояснення.)

  • Уникайте повторення великих частин тексту. Просто пояснюйте один раз, і надалі посилайтеся на це пояснення.

    Для загальної термінології визначайте термін :term: у глосарії – glossary.

  • Уникайте переліків подібних опцій, таких як перелічування кожної передустави або кожного набору частот кадрів у меню вибору.

    Їх вміст може бути узагальнений або просто пропущений. – Такі переліки показують лише те, що вже є очевидним в інтерфейсі, та зрештою є великим обсягом тексту для читання та підтримування.

  • Уникайте документування змін у Blender’і між випусками, саме для цього і призначені примітки щодо випуску. Нам потрібно документувати лише поточний стан Blender’а.

  • Допоки одиниця значення вимірюється нечітко і непередбачувано, відсутня необхідність згадувати про це.

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

    Як останній засіб, ви можете додавати коментар (який не показується на сторінці HTML, але корисний для інших редакторів):

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

Glossary – Глосарій#

Це секція про підрозділ «Глосарій» – Glossary, де ми визначаємо загальні терміни у Blender’і та комп’ютерній графіці.

Емпіричні правила:

  • Визначайте термін до того, як давати будь-яку подальшу щодо нього інформацію.

  • Уникайте використання конструкцій, таких як, «це є» або «xyz є», перед визначенням терміну.

  • Уникайте повторення терміну тут же або використання його у своєму ж визначенні.

  • Уникайте додання термінів, відсутніх в інтерфейсі Blender’а або у цьому довіднику.

  • Уникайте надто довгих записів. Якщо потрібно пояснити складний термін, доповніть його зовнішніми посиланнями.

  • Уникайте дублювання документації; якщо пояснення терміну первісно зосереджується на іншому розділі посібника (наприклад, якщо термін є іменем засобу) або тільки посиланням на той розділ, а також уникайте створення запису у глосарії повністю.

  • Посилання URL додаються у кінець та форматуються так, як приклад:

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

Examples – Приклади#

Цей запис:

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.

Може бути записаний так, з униканням «він є»:

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