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

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

Как писать?

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

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

Изучите также синтаксис. Чтобы просматривать статью прямо при написании, можно воспользоваться редактором с предпросмотром.

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

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

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

Мелкие правки

Чтобы вносить вклад в документацию, вам нужна учётная запись на GitHub.

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

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

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

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

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

Правьте документацию так:

На 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 с изображениями, которые можно вставлять в страницы документации.