Документация в GitLab — это подход к созданию, хранению и управлению документацией с использованием платформы GitLab. Документация размещается в репозиториях вместе с кодом или отдельно и поддерживается по тем же принципам, что и разработка программного обеспечения.
Такой подход является частью практики docs-as-code (документация как код) и широко используется в современных IT-командах.
Что включает документация в GitLab
В GitLab можно хранить и управлять разными видами документации:
- техническая документация;
- API-документация;
- руководства пользователя;
- инструкции по настройке и развертыванию;
- архитектурная документация;
- журналы изменений и примечания к выпуску;
- внутренние базы знаний.
Документы обычно пишутся в формате Markdown (хотя GitLab также поддерживает AsciiDoc и reStructuredText) и хранятся в репозитории.
Основные возможности GitLab для документации
Платформа GitLab предоставляет ряд инструментов для работы с документацией.
Версионирование в Git
Документация хранится вместе с кодом и версионируется.
Merge Request (MR)
Используются для обсуждения и согласования изменений в документации.
Wiki в GitLab
Позволяет вести отдельную базу знаний, связанную с проектом.
CI/CD
Позволяет автоматически публиковать документацию (например, как статический сайт). CI/CD также используется для валидации документации (проверка ссылок, линтинг Markdown, сборка документации в процессе пайплайна)
GitLab Pages
Инструмент для размещения документации в виде веб-сайта.
Как работает документация в GitLab
Процесс работы обычно выглядит так:
- Документация хранится в репозитории или Wiki;
- Изменения вносятся через коммиты, коммиты делаются в ветках (branches);
- Для проверки создаются merge request;
- Команда обсуждает и утверждает изменения;
- Документация автоматически публикуется (например, через GitLab Pages).
Для чего нужна документация в GitLab
Использование GitLab для документации позволяет:
- синхронизировать документацию с кодом;
- упростить командную работу;
- отслеживать историю изменений;
- автоматизировать публикацию;
- поддерживать документацию в актуальном состоянии.
Где используется документация в GitLab
Такой подход применяется в:
- разработке программного обеспечения;
- DevOps и инфраструктурных командах;
- open-source проектах;
- продуктовых командах;
- создании технической и API-документации.
Преимущества
- единое пространство для кода и документации;
- прозрачность изменений;
- удобная совместная работа;
- интеграция с CI/CD;
- возможность публикации документации как сайта.