Как внести вклад в документацию ******************************* .[perex] Внесение вклада в документацию — одно из самых полезных занятий, поскольку вы помогаете другим понять фреймворк. Как писать? ----------- Документация предназначена в первую очередь для людей, которые знакомятся с темой. Поэтому она должна соответствовать нескольким важным пунктам: - Начните с простого и общего. К более сложным темам переходите только в конце - Старайтесь объяснить вещь как можно лучше. Попробуйте, например, сначала объяснить тему коллеге - Приводите только ту информацию, которая действительно нужна пользователю по данной теме - Убедитесь, что ваша информация действительно верна. Каждый код протестируйте - Будьте краткими - то, что вы напишете, сократите наполовину. А потом, возможно, еще раз - Экономьте на выделениях всех видов, от жирного шрифта до рамок типа `.[note]` - В коде соблюдайте [Стандарт кодирования |Coding Standard] Освойте также [синтаксис |syntax]. Для предварительного просмотра статьи во время ее написания вы можете использовать [редактор с предпросмотром |https://editor.nette.org/]. Языковые версии --------------- Основным языком является английский, поэтому ваши изменения должны быть на английском. Если английский не является вашей сильной стороной, используйте [DeepL Translator |https://www.deepl.com/translator], и другие проверят ваш текст. Перевод на другие языки будет выполнен автоматически после утверждения и доработки вашего изменения. Незначительные правки --------------------- Для внесения вклада в документацию необходимо иметь учетную запись на [GitHub|https://github.com]. Самый простой способ внести небольшое изменение в документацию — использовать ссылки в конце каждой страницы: - *Показать на GitHub* откроет исходную версию данной страницы на GitHub. Затем достаточно нажать кнопку `E` и можно начинать редактировать (необходимо быть авторизованным на GitHub) - *Открыть предпросмотр* откроет редактор, где вы сразу увидите и итоговый визуальный вид Поскольку [редактор с предпросмотром |https://editor.nette.org/] не имеет возможности сохранять изменения прямо на GitHub, необходимо после завершения правок скопировать исходный текст в буфер обмена (кнопкой *Copy to clipboard*), а затем вставить его в редактор на GitHub. Под полем редактирования находится форма для отправки. Здесь не забудьте кратко изложить и объяснить причину вашей правки. После отправки создается так называемый pull request (PR), который можно дальше редактировать. Более крупные правки -------------------- Более подходящим, чем использование интерфейса GitHub, является знакомство с основами работы с системой контроля версий Git. Если вы не владеете работой с Git, вы можете ознакомиться с руководством [git - простое руководство |https://rogerdudler.github.io/git-guide/] и, при необходимости, использовать один из множества [графических клиентов |https://git-scm.com/downloads/guis]. Документацию редактируйте следующим образом: 1) на GitHub создайте [форк |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] репозитория [nette/docs |https://github.com/nette/docs] 2) этот репозиторий [клонируйте |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] на свой компьютер 3) затем в [соответствующей ветке |#Структура документации] внесите изменения 4) проверьте лишние пробелы в тексте с помощью инструмента [Code-Checker |code-checker:] 4) сохраните изменения (сделайте коммит) 6) если вы удовлетворены изменениями, отправьте (push) их на GitHub в ваш форк 7) оттуда отправьте их в репозиторий `nette/docs`, создав [pull request|https://help.github.com/articles/creating-a-pull-request] (PR) Обычно вы будете получать комментарии с замечаниями. Следите за предлагаемыми изменениями и вносите их. Предлагаемые изменения добавляйте как новые коммиты и снова отправляйте на GitHub. Никогда не создавайте новый pull request для изменения существующего pull request. Структура документации ---------------------- Вся документация размещена на GitHub в репозитории [nette/docs |https://github.com/nette/docs]. Актуальная версия находится в ветке master, старые версии размещены в ветках, таких как `doc-3.x`, `doc-2.x`. Содержимое каждой ветки делится на основные папки, представляющие отдельные области документации. Например, `application/` соответствует https://doc.nette.org/ru/application, `latte/` соответствует https://latte.nette.org и т.д. Каждая такая папка содержит подпапки, представляющие языковые версии (`en`, `ru`, ...), и, возможно, подпапку `files` с изображениями, которые можно вставлять на страницы документации.

Как внести вклад в документацию

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

Как писать?

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

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

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

Языковые версии

Основным языком является английский, поэтому ваши изменения должны быть на английском. Если английский не является вашей сильной стороной, используйте DeepL Translator, и другие проверят ваш текст.

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

Незначительные правки

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

Самый простой способ внести небольшое изменение в документацию — использовать ссылки в конце каждой страницы:

Показать на GitHub откроет исходную версию данной страницы на GitHub. Затем достаточно нажать кнопку E и можно начинать редактировать (необходимо быть авторизованным на GitHub)
Открыть предпросмотр откроет редактор, где вы сразу увидите и итоговый визуальный вид

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

Более крупные правки

Более подходящим, чем использование интерфейса GitHub, является знакомство с основами работы с системой контроля версий Git. Если вы не владеете работой с Git, вы можете ознакомиться с руководством git – простое руководство и, при необходимости, использовать один из множества графических клиентов.

Документацию редактируйте следующим образом:

на GitHub создайте форк репозитория 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.