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

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

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

User Focused – Орієнтованість на Користувача: Цей посібник написаний для людей, що отримали освіту в галузі комп’ютерної графіки, котрі розуміють основи 3D та/або знають інше програмне забезпечення у сфері 3D. Хоча деякі області комп’ютерної графіки є високо технічними, цей посібник повинен бути зрозумілим для не-технічних користувачів.
Complete – Завершеність: Посібник надає детальний функціональний опис всіх функціональностей, засобів та опцій у Blender. Хоча існує канонічне джерело істини для кожної з ключових областей Blender’а, це не означає, що ми маємо документувати кожну дрібну деталь. Посібник повинен надавати інформацію про те, що таке певна функціональність, як її використовувати та яке її призначення. Більше базової інформації повинно надатися при необхідності дати глибше розуміння конвеєра у галузі 3D.
Concise – Стислість: Computer graphics is an incredibly interesting field. There are many rules, exceptions to those rules, and interesting details. However, expanding into details can add unnecessary content; therefore, keep the text concise and relevant to the end user.
Maintainable – Підтримуваність: Keep in mind that Blender has frequent releases, so try to write content that will not have to be redone the moment some small change is made. This also helps a small documentation community maintain the manual.

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).
Турбуйтеся про граматику, відповідний підбір слів та використання простої Англійської.
Keep sentences short and clear.
Визначення того, чому і як та чи інша опція може бути корисною, – це добра ідея.
Якщо ви не впевнені у тому, як функція працює, спитайте когось ще або знайдіть того, хто її розробив та спитайте його.

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

Avoid writing in the first person perspective, about yourself, or about your own opinions.
Уникайте обтічних слів weasel words та непотрібної розпливчастості, наприклад:

«Перезавантаження файлу можливо вирішить проблему»

«Більшість людей не використовують цю опцію, тому що …»
Уникайте включення специфічних деталей, таких як:

«Blender має 23 різних типи модифікаторів.»

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

These details are not useful for users and become quickly outdated.
Уникайте документування дефектів.

Blender often has hundreds of bugs fixed between releases, so the manual cannot be expected to keep up.

Проблеми, що відомі розробникам та не плануються вирішуватися до наступного випуску, можуть документуватися як відомі обмеження Known Limitations. У деяких випадках може найкраще включити їх у розділ про усунення несправностей – troubleshooting.
Avoid product placements, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.
Уникайте технічних пояснень щодо математичної/алгоритмічної імплементації функціональності, якщо є простіший спосіб пояснити її.

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

Для загальної термінології визначайте термін :term: у глосарії – glossary.
Avoid listing every option in a menu, such as frame rates.

Їх вміст може бути узагальнений або просто пропущений. – Такі переліки показують лише те, що вже є очевидним в інтерфейсі, та зрештою є великим обсягом тексту для читання та підтримування.
Уникайте документування змін у 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
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have 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 line interpolated between Control Vertices.
   Common types include Bézier and NURBS.