РОСА Документация

Добро пожаловать в репозиторий технической документации РОСА.

Здесь применяется подход Docs-as-Code (DAC): документация пишется как код, хранится в Git и проходит те же процессы ревью, тестирования и доставки, что и программное обеспечение.

Документация как процесс

В DAC применяются практики разработки ПО:

• Все изменения проходят через Merge Request (Мердж, MR).
• Обсуждения ведутся прямо в MR с использованием комментариев, pending-статусов и разрешения споров.
• Каждый MR — это законченная единица работы, связанная с задачей по обновлению документации.
• Правки заносятся в ветку develop, далее передаются в отдел качества для утверждения и переноса в ветку master.

Начало работы

Перед началом работы необходимо получить доступ к репозиторию git.rosa.ru (r.mahin@rosa.ru).

Подготовка

1. Перейти на сайт git.rosa.ru и авторизоваться с помощью выданных ранее логина и пароля.
2. Перейти в каталог knowledge/rosadoc-content;
3. Нажать кнопку "EDIT" и выбрать "Web IDE";
4. Раскрыть в левом меню каталог content.
5. Выбрать каталог продукта для редактирования.

Создание нового документа

1. Создать новый каталог в content и вызвать его контекстное меню, выбрать "Upload".
2. Выбрать md-файлы для загрузки

Отправка MR

Правила оформления MR:

Работа с конфликтами

При возникновении конфликтов:

• Свериться со своими исходными правками (рекомендуется вести краткие заметки).
• Не удалять чужие изменения без согласования.
• Открыть обсуждение в MR.

Процесс согласования:

Этап 1: Отдел документирования (внутреннее согласование)

Все правки сначала проходят внутреннее согласование внутри команды технических писателей.

Согласование идет через комментарии в MR (dev) и статус “Pending”, чтобы:

• обосновать выбор формулировок;
• обсудить структуру раздела;
• согласовать терминологию.

Только после достижения консенсуса внутри отдела документирования работа переводится на этап экспертизы.

Если нет уверенности в формулировке, оставляется комментарий с pending и предложением альтернативы.

Этап 2: Отдел качества (внешнее согласование)

После внутреннего одобрения MR отправляется на ветку develop.

Участники внешней экспертизы (Отдел качества, Разработчики, Тестировщики) проверяют:

• техническую точность;
• соответствие функциональности;
• полноту покрытия сценариев.

Замечания обсуждаются в том же MR.

Важно: финальное слияние (merge) разрешено только после прохождения обоих этапов (approved by all).

Как использовать дискуссии в MR

• Комментарии — для замечаний по конкретной строке.
• Общие комментарии — для вопросов по структуре или логике.
• Статус “Pending” — если предлагается правка, но она требует обсуждения или подтверждения.
• Разрешение дискуссии — только после того, как все участники согласны.

Локальный редактор документаций VS Code

Установка и настройка

Установка VS Code

1. Перейти на официальный сайт: https://code.visualstudio.com/
2. Скачать и установить редактор для используемой операционной системы (Windows, macOS или Linux).

Установка расширений

Открыть VS Code и установить расширения через Marketplace (вкладка Extensions слева или Ctrl+P и ввести команду):

• LaTeX Workshop — основное расширение для работы с .tex-файлами.
  Команда: ext install latex-workshop.
• Code Spell Checker — базовый инструмент для проверки орфографии.
  Команда: ext install streetsidesoftware.code-spell-checker.
• Russian - Code Spell Checker — словарь для проверки орфографии на русском языке.
  Команда: ext install streetsidesoftware.code-spell-checker-russian.

Важно! После установки расширений перезапустить VS Code.

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

Что такое Changes?

Когда редактируется файл, VS Code показывает его в разделе Source Control (значок с вилкой и листом слева).
Это — локальные правки, которые ещё не отправлены в общий репозиторий.

Как проверить изменения перед отправкой?

1. Нажать на значок Source Control (или Ctrl+Shift+G).
2. Появится список изменённых файлов.
3. Нажать на имя файла — откроется сравнение: старая версия ←→ измененная версия.
4. Убедиться, что:
   • Нет случайных опечаток,
   • Не удалено лишнее,
   • Все правки относятся к одной задаче.

Как сохранить и отправить изменения (Push)?

Создать отдельную ветку

Ветка — это отдельная "копия" проекта, где редактируется текст без риска потерять основную версию.

1. Нажать на кнопку выбора ветки, выбрать "+Create new branch"
2. Указать название ветки на английском языке, нажать клавишу Enter

Зафиксировать изменения (Commit)

1. В разделе Source Control ввести краткое описание коммита ЦУ: Обновлен раздел 1.2 по задаче 123
2. Нажать флажок (✓ Commit) или Ctrl+Enter.

Commit — это "снимок" внесенных изменений. Он сохраняется локально на компьютере пользователя.

Отправить изменения в облако (Push)

1. После первого коммита нажать кнопку "Publish Branch".
2. Это действие называется Push — оно отправляет текущую ветку и все коммиты в общий репозиторий.

Push = "загрузить изменения в облако"
После Push текущая ветка становится видна другим, и можно создать Merge Request (MR).

Что делать дальше?

1. Перейти на страницу репозитория https://git.rosa.ru/knowledge/rosadoc-content
2. Нажать кнопку Create merge request.
3. Заполнить поля заголовка, описания (что сделано, зачем) и назначить роль ревьюера (Евгений Киржацких).
4. Отправьте MR на согласование.

Merge Request (MR) — это запрос на проверку внесенных правок и публикацию измененных документов.