Вказівки щодо змісту

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

Ми хочемо досягти двох цілей:

Співпереживайте нашим користувачам. Ми повинні писати так, щоб їм було легко вчитися з документів.
Напишіть повний довідковий посібник. Наша мета тут не в тому, щоб навчити основам програмування. Натомість наша мета — надати довідку про те, як працюють функції Godot.

Настанови та принципи

Нижче наведено вказівки, яких ми повинні прагнути дотримуватися. Однак це не жорсткі правила: іноді тема потребує порушення одного чи кількох із них. Але ми повинні прагнути досягти двох перерахованих вище цілей.

Написання повної та доступної документації

Функція не існує, якщо вона не задокументована. Якщо користувач не може знайти інформацію про функцію та як вона працює, для нього вона не існує. Ми повинні переконатися, що ми висвітлюємо все, що робить Godot.

Примітка

Додаючи або оновлюючи функцію двигуна, команда документації повинна знати про це. Співавтори повинні відкрити проблему в репозиторії godot-docs, коли їхню роботу буде об’єднано та потребуватиме документації.

Зробіть усе можливе, щоб зберігати документи менше 1000 слів. Якщо сторінка перевищує цей поріг, подумайте про розділення її на дві частини. Обмеження розміру сторінки змушує нас писати коротко та розбивати великі документи так, щоб кожна сторінка була зосереджена на певній проблемі.

Кожна сторінка чи розділ сторінки має чітко вказувати, яку проблему вона вирішує та чого навчить користувача. Користувачі повинні знати, чи читають вони правильний посібник для вирішення проблем, з якими вони стикаються. Наприклад, замість того, щоб писати заголовок «Сигнали», спробуйте написати «Реакція на зміни за допомогою сигналів». Друга назва пояснює призначення сигналів.

Примітка

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

Якщо сторінка передбачає конкретні знання про інші функції Godot, згадайте про це та вкажіть посилання на відповідну документацію. Наприклад, сторінка про фізику може використовувати сигнали, у цьому випадку ви можете зауважити, що підручник із сигналів є обов’язковою умовою. Ви також можете посилатися на інші веб-сайти для попередніх умов, що виходять за рамки документації. Наприклад, ви можете зробити посилання на вступ до програмування в посібнику з початку роботи або веб-сайт, який викладає теорію математики в математичному розділі.

Обмеження когнітивного навантаження

Обмежте когнітивне навантаження, необхідне для читання документації. Чим простішою та зрозумілішою мовою ми користуємося, тим ефективніше стає для людей навчання. Ви можете зробити це:

Представляючи лише одну нову концепцію за раз, коли це можливо.
Використовуючи просту англійську мову, як ми рекомендуємо в наших інструкціях з написання.
Включно з одним або кількома конкретними прикладами використання. Віддавайте перевагу прикладу з реального світу, а не такому, який використовує такі імена, як foo, bar або baz.

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

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

Примітка

Основи програмування є необхідною умовою для використання такого складного механізму, як Godot. Розмова про змінні, функції чи класи прийнятна. Але ми повинні віддавати перевагу простій мові, а не специфічній термінології, як-от «метапрограмування». Якщо вам потрібно використовувати точні терміни, обов’язково дайте їм визначення.