/rdw-test-docs

Документация для тестовой группы на производстве РДВ Технолоджи

Primary LanguageTypeScript

Для пользователей

Это руководство поможет вам внести изменения в нашу документацию непосредственно через веб-интерфейс GitHub. Вам не потребуется устанавливать какое-либо программное обеспечение или иметь специальные навыки — все, что нужно, это браузер и доступ в интернет.

Что вам понадобится

  • Браузер: у кого его нет?
  • Аккаунт на GitHub: если у вас его еще нет, перейдите на github.com и зарегистрируйтесь. Это бесплатно и займет всего несколько минут.

Пошаговая инструкция

1. Переход к репозиторию документации

  1. Откройте браузер и перейдите по ссылке на наш репозиторий документации: rdw-test-docs.
  2. Вы попадете на главную страницу репозитория, где хранится весь код и файлы нашей документации.

2. Навигация по структуре файлов

  1. В репозитории вы увидите список папок и файлов. Например:
    • blog/
    • docs/
    • src/
    • static/
    • ...

Содержимое репозитория

  1. Для редактирования документации нажмите на папку docs/, чтобы открыть ее содержимое и увидеть все файлы, относящиеся к документации.

3. Поиск нужного файла

  1. Внутри папки docs/ найдите файл, который вы хотите отредактировать. Например, intro.md.
  2. Нажмите на название файла, чтобы открыть его.

4. Редактирование файла

  1. С правой стороны вы увидите иконку карандаша иконка карандаша. Нажмите на нее, чтобы начать редактирование.

Кнопка карандаша

  1. Откроется редактор с содержимым файла в формате Markdown.

5. Внесение изменений

  1. Внесите необходимые правки в текст. Используйте синтаксис Markdown для форматирования. Если вы не знакомы с Markdown, ознакомьтесь с нашим руководством по Markdown.
  2. Просмотрите свои изменения, чтобы убедиться в их правильности.

6. Предложение изменений (создание Pull Request)

  1. Справа наверху появится зелёная кнопка "Commit changes...". Кнопка карандаша
  2. В поле "Commit message" введите краткое описание ваших изменений. Например: Обновление раздела с инструкцией по тестированию серверов.
  3. В поле "Extended description" можно добавить более подробное описание (необязательно, но желательно). Кнопка карандаша
  4. Выберите опцию "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", иначе это приведёт к неразберихе.
  5. Нажмите кнопку "Propose changes".

7. Создание Pull Request

  1. После нажатия "Propose changes" вы будете перенаправлены на страницу сравнения изменений. pull-request.png

  2. Назначьте пустые поля (желательно, но необязательно)

    1. Ревьюеры - это те пользователи, которые будут проверять предложенные вами изменения, временно этим занимаюсь я (WaneTol72)
    2. Назначенные пользователи - это те, кто назначен на эти изменения, если вы хотите задействовать других коллег в правках, поэтому там помимо себя ("assign yourself") можно назначить и других пользователей
    3. Тэги - тэги они и в африке тэги! А если вкратце, то это краткая пометка чем являются правками, если это простое изменение документации, то помечайте как "Документация"
    4. Проекты, этот пункт вы можете пропустить, но в будущем их можно будет использовать, это некоторая доска с задачами, которыми можно удобно управлять и выполнять.
    5. Мэйлстоуны - грубо говоря, версии, которые ещё не вышли, а только готовятся. Например, мы создали версию 1,5 под сервера, цель её - дописать документацию под сервера, все правки связанные с серверами стоит прикреплять к этому мейлстоуну.
    6. Краткое описание предложенных изменений
    7. Не краткое (ещё это называют подробное) описание предложенных изменений
    8. Кнопка создать запрос на изменение (финиш)

  3. Нажмите кнопку "Create pull request".

  4. Готово! Ваш запрос будет выглядеть примерно так: pull-request-success.png

  5. Ожидайте, когда его примут или начнутся адские дебаты насчёт вносимых правок в этой теме. (по сути это отдельная тема)

8. Ожидание проверки и слияния

  • Ваше предложение (Pull Request) будет рассмотрено ответственными за документацию.
  • Если возникнут вопросы или потребуется дополнительная информация, с вами свяжутся через комментарии в Pull Request.
  • После одобрения ваши изменения будут добавлены в основную версию документации.

Полезные советы

  • Внимательно проверяйте текст: перед отправкой убедитесь в отсутствии ошибок и опечаток.
  • Следуйте стилю документации: это поможет сохранить единообразие во всех разделах.
  • Будьте ясны и точны: старайтесь излагать мысли понятно и лаконично.
  • Не стесняйтесь задавать вопросы

Часто задаваемые вопросы

Когда я увижу свои правки на сайте?

  • Git - это такая система, которая позволяет буквально собирать обновления по кусочкам и в определённый момент или дату делать релиз, что является очень удобным для отлаживания ошибок и полировки всех ньюансов, поэтому изменения, особенно большие и ёмкие будут применяться спустя пару дней, после одобрения всех участников.

Что делать, если я ошибся в своих изменениях?

  • Не переживайте! Вы всегда можете внести дополнительные правки в свой Pull Request или попросить отменить его. Просто откройте ваш Pull Request и внесите необходимые изменения.

Могу ли я отредактировать несколько файлов одновременно?

  • Да, вы можете внести изменения в несколько файлов, но для простоты рекомендуем начинать с одного файла, особенно если вы новичок.

Нужно ли мне знать программирование?

  • Нет, для редактирования документации знания программирования не требуются. Достаточно базовых навыков работы с текстом и понимания синтаксиса Markdown.

Заключение

Ваш вклад очень важен для нас. Совместными усилиями мы улучшаем качество документации, делая ее более понятной и полезной для всех сотрудников.

Спасибо за вашу помощь и инициативу!