Nette Documentation Preview

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

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


Как писать?
-----------

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

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

Изучите также [синтаксис |syntax]. Чтобы просматривать статью прямо при написании, можно воспользоваться [редактором с предпросмотром |https://editor.nette.org/].


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

Английский - основной язык, так что ваши изменения в идеале должны быть на английском. Если английский не ваша сильная сторона, воспользуйтесь [переводчиком DeepL |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 - the simple guide |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 |tools:code-checker].
5) Сохраните (закоммитьте) изменения.
6) Если изменения вас устраивают, отправьте их на GitHub в свой форк.
7) Оттуда отправьте их в репозиторий `nette/docs`, создав [pull request|https://help.github.com/articles/creating-a-pull-request] (PR).

Обычно вы получаете замечания с предложениями. Следите за предлагаемыми изменениями и вносите их. Добавляйте предложенные изменения новыми коммитами и снова отправляйте их на GitHub. Никогда не создавайте новый pull request только для того, чтобы изменить существующий.


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

Вся документация находится на GitHub в репозитории [nette/docs |https://github.com/nette/docs]. Текущая версия - в ветке `master`, а более старые версии находятся в ветках вроде `doc-3.x`, `doc-2.x`.

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

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

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

Как писать?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. На GitHub создайте форк репозитория nette/docs.
  2. Клонируйте этот репозиторий к себе на компьютер.
  3. Затем вносите изменения в подходящей ветке.
  4. Проверьте текст на лишние пробелы инструментом Code-Checker.
  5. Сохраните (закоммитьте) изменения.
  6. Если изменения вас устраивают, отправьте их на GitHub в свой форк.
  7. Оттуда отправьте их в репозиторий 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 с изображениями, которые можно вставлять в страницы документации.