Як зробити внесок у документацію

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

Як писати?

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

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

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

Мовні версії

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

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

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

Для внесення внеску в документацію необхідно мати обліковий запис на GitHub.

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

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

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

Більші правки

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

Документацію редагуйте таким чином:

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

Зазвичай ви отримуватимете коментарі із зауваженнями. Слідкуйте за запропонованими змінами та враховуйте їх. Запропоновані зміни додайте як нові коміти та знову надішліть на GitHub. Ніколи не створюйте новий pull request для зміни існуючого pull request.

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

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

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