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

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

Как писать?

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

Начинайте с простых и общих тем. В конце переходите к более сложным темам.
Старайтесь объяснять тему как можно понятнее. Например, попробуйте сначала объяснить тему коллеге.
Предоставляйте только ту информацию, которую пользователю действительно необходимо знать по данной теме.
Убедитесь, что ваша информация точна. Тестируйте каждый код
Будьте лаконичны – сократите то, что вы пишете, вдвое. А затем не стесняйтесь сделать это снова.
Используйте выделение экономно, от жирного шрифта до рамок типа .[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. Никогда не создавайте новый pull request только для того, чтобы изменить существующий.

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

Вся документация находится на GitHub в репозитории nette/docs. Текущая версия находится в ветке master, а старые версии расположены в ветках doc-3.x, doc-2.x.

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