Путівник зі Стилю Написання – Writing Style Guide¶
Первісні цілі – Primary Goals¶
Головні цілі цього довідника наступні:
- Орієнтованість на користувача – User Focused
Цей довідник написаний для людей, освічених у комп’ютерній графіці, котрі розуміють основи 3D та/або знають інше програмне забезпечення 3D. Хоча деякі області комп’ютерної графіки є високо технічними, цей довідник повинен зберігати зрозумілість для не-технічних користувачів.
- Завершеність – Complete
Довідник надає деталізований функціональний опис всіх функцій, засобів та опції у Blender. Хоча є канонічне джерело істини для кожної з ключових областей Блендера, це не означає, що ми повинні документувати кожну дрібну деталь. Цей довідник повинен надавати інформацію про те, що така функція є, як її використовувати та її призначення. Більш ґрунтовна інформація повинна надаватися, коли необхідно дати глибше розуміння конвеєра 3D.
- Лаконічність – Concise
Комп’ютерна графіка є надзвичайно цікавою галуззю, тут є багато правил, винятків з цих правил та цікавих деталей. Заглиблення у деталі може давати непотрібний вміст, а тому слід зберігати текст лаконічним та відповідним темі.
- Підтримуваність – Maintainable
Майте на увазі, що Blender має часті випуски, а тому намагайтеся писати вміст так, щоб він не потребував переробки через незначні зміни. Це також допомагає утримувати невелику спільноту з документації для підтримання цього довідника.
Настанови щодо вмісту – Content Guidelines¶
Щоб підтримувати узгоджений стиль писання у межах цього довідника, будь ласка, тримайте в умі написане на цій сторінці та тільки тоді відхиляйтеся від цього, коли є на те значна причина.
Емпіричні правила:
Перевірка правопису настійно рекомендується.
Використовуйте Американську Англійську – American English (наприклад: modeling, а не modelling, color, а не colour) також для форматування чисел (наприклад: 2,718.28, а не 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.