Долучайтеся до створення документації

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

Як писати?

Документація в першу чергу призначена для людей, які є новачками в темі. Тому вона повинна відповідати декільком важливим пунктам:

Починайте з простих і загальних тем. Переходьте до більш складних тем наприкінці
Намагайтеся пояснювати тему якомога зрозуміліше. Наприклад, спробуйте спочатку пояснити тему колезі
Надавайте лише ту інформацію, яку користувачеві дійсно потрібно знати з даної теми
Переконайтеся, що ваша інформація точна. Тестуйте кожен код
Будьте лаконічними – скорочуйте те, що пишете, вдвічі. А потім не соромтеся робити це ще раз
Економно використовуйте виділення, від напівжирного шрифту до рамок, таких як .[note]
Дотримуйтесь стандарту кодування в коді

Також вивчайте синтаксис. Для попереднього перегляду статті під час написання ви можете скористатися редактором попереднього перегляду.

Мовні мутації

Англійська є основною мовою, тому ваші зміни повинні бути англійською. Якщо англійська не є вашою сильною стороною, скористайтеся DeepL Перекладачем, і інші перевірять ваш текст.

Переклад на інші мови буде зроблено автоматично після затвердження та уточнення вашої правки.

Тривіальні правки

Щоб зробити свій внесок у документацію, вам потрібно мати обліковий запис на GitHub.

Найпростіший спосіб внести невелику зміну в документацію – скористатися посиланнями в кінці кожної сторінки:

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

Оскільки редактор поперед нього перегляду не має можливості зберігати зміни безпосередньо на GitHub, вам потрібно скопіювати вихідний текст в буфер обміну (за допомогою кнопки Копіювати в буфер обміну), а потім вставити його в редактор на GitHub. Під полем для редагування знаходиться форма для відправки. Тут не забудьте коротко підсумувати і пояснити причину вашого редагування. Після відправки створюється так званий pull request (PR), який можна надалі редагувати.

Більші редагування

Доцільніше бути знайомим з основами роботи з системою контролю версій Git, ніж покладатися виключно на інтерфейс GitHub. Якщо ви не знайомі з Git'ом, ви можете звернутися до git – простий посібник і розглянути можливість використання одного з багатьох доступних графічних клієнтів.

Редагуйте документацію наступним чином:

на GitHub створіть форк сховища nette/docs
клонуйте цей репозиторій на свій комп'ютер
потім внесіть зміни у відповідній гілці
перевірте наявність зайвих пробілів у тексті за допомогою інструменту Code-Checker
збережіть (зафіксуйте) зміни
якщо зміни вас влаштовують, перенесіть їх на GitHub у свій форк
звідти відправте їх до репозиторію nette/docs, створивши pull request (PR)

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

Структура документації

Вся документація знаходиться на GitHub в репозиторії nette/docs. Поточна версія знаходиться в головній гілці, тоді як старіші версії знаходяться в гілках doc-3.x, doc-2.x.

Вміст кожної гілки розділено на основні папки, що представляють окремі області документації. Наприклад, application/ відповідає https://doc.nette.org/en/application, latte/ відповідає https://latte.nette.org і т.д. Кожна з цих папок містить підпапки, що представляють мовні мутації (cs, en, …) і додатково підпапку files з зображеннями, які можна вставляти на сторінки документації.