Это руководство поможет вам внести изменения в нашу документацию непосредственно через веб-интерфейс GitHub. Вам не потребуется устанавливать какое-либо программное обеспечение или иметь специальные навыки — все, что нужно, это браузер и доступ в интернет.
- Браузер: у кого его нет?
- Аккаунт на GitHub: если у вас его еще нет, перейдите на github.com и зарегистрируйтесь. Это бесплатно и займет всего несколько минут.
- Откройте браузер и перейдите по ссылке на наш репозиторий документации: rdw-test-docs.
- Вы попадете на главную страницу репозитория, где хранится весь код и файлы нашей документации.
- В репозитории вы увидите список папок и файлов. Например:
blog/
docs/
src/
static/
- ...
- Для редактирования документации нажмите на папку
docs/
, чтобы открыть ее содержимое и увидеть все файлы, относящиеся к документации.
- Внутри папки
docs/
найдите файл, который вы хотите отредактировать. Например,intro.md
. - Нажмите на название файла, чтобы открыть его.
- Откроется редактор с содержимым файла в формате Markdown.
- Внесите необходимые правки в текст. Используйте синтаксис Markdown для форматирования. Если вы не знакомы с Markdown, ознакомьтесь с нашим руководством по Markdown.
- Просмотрите свои изменения, чтобы убедиться в их правильности.
- Справа наверху появится зелёная кнопка "Commit changes...".
- В поле "Commit message" введите краткое описание ваших изменений. Например:
Обновление раздела с инструкцией по тестированию серверов
. - В поле "Extended description" можно добавить более подробное описание (необязательно, но желательно).
- Выберите опцию "Create a new branch for this commit and start a pull request" или "Commit directly to the master branch", если у вас есть разрешение - это сразу внесёт изменения, минуя пункты 7 и 8. Не злоупотребляйте "Commit directly to the master branch", иначе это приведёт к неразберихе.
- Нажмите кнопку "Propose changes".
-
После нажатия "Propose changes" вы будете перенаправлены на страницу сравнения изменений.
-
Назначьте пустые поля (желательно, но необязательно)
- Ревьюеры - это те пользователи, которые будут проверять предложенные вами изменения, временно этим занимаюсь я (WaneTol72)
- Назначенные пользователи - это те, кто назначен на эти изменения, если вы хотите задействовать других коллег в правках, поэтому там помимо себя ("assign yourself") можно назначить и других пользователей
- Тэги - тэги они и в африке тэги! А если вкратце, то это краткая пометка чем являются правками, если это простое изменение документации, то помечайте как "Документация"
- Проекты, этот пункт вы можете пропустить, но в будущем их можно будет использовать, это некоторая доска с задачами, которыми можно удобно управлять и выполнять.
- Мэйлстоуны - грубо говоря, версии, которые ещё не вышли, а только готовятся. Например, мы создали версию 1,5 под сервера, цель её - дописать документацию под сервера, все правки связанные с серверами стоит прикреплять к этому мейлстоуну.
- Краткое описание предложенных изменений
- Не краткое (ещё это называют подробное) описание предложенных изменений
- Кнопка создать запрос на изменение (финиш)
-
Нажмите кнопку "Create pull request".
-
Ожидайте, когда его примут или начнутся адские дебаты насчёт вносимых правок в этой теме. (по сути это отдельная тема)
- Ваше предложение (Pull Request) будет рассмотрено ответственными за документацию.
- Если возникнут вопросы или потребуется дополнительная информация, с вами свяжутся через комментарии в Pull Request.
- После одобрения ваши изменения будут добавлены в основную версию документации.
- Внимательно проверяйте текст: перед отправкой убедитесь в отсутствии ошибок и опечаток.
- Следуйте стилю документации: это поможет сохранить единообразие во всех разделах.
- Будьте ясны и точны: старайтесь излагать мысли понятно и лаконично.
- Не стесняйтесь задавать вопросы
- Git - это такая система, которая позволяет буквально собирать обновления по кусочкам и в определённый момент или дату делать релиз, что является очень удобным для отлаживания ошибок и полировки всех ньюансов, поэтому изменения, особенно большие и ёмкие будут применяться спустя пару дней, после одобрения всех участников.
- Не переживайте! Вы всегда можете внести дополнительные правки в свой Pull Request или попросить отменить его. Просто откройте ваш Pull Request и внесите необходимые изменения.
- Да, вы можете внести изменения в несколько файлов, но для простоты рекомендуем начинать с одного файла, особенно если вы новичок.
- Нет, для редактирования документации знания программирования не требуются. Достаточно базовых навыков работы с текстом и понимания синтаксиса Markdown.
Ваш вклад очень важен для нас. Совместными усилиями мы улучшаем качество документации, делая ее более понятной и полезной для всех сотрудников.
Спасибо за вашу помощь и инициативу!