Привет! Меня зовут Александр Мачулин, я сооснователь Gramax и совладелец компании ics-it.

Мы разрабатываем аналитические системы для Pharma и FMCG-производителей. Наши клиенты в последнее время все чаще просят писать и хранить проектную документацию в их системах: Confluence, ServiceNow и т.д. При этом у нас процесс разработки документации построен через собственную систему с подходом Docs as Code. Потому поддержка документации в системе клиента будет дополнительным препятствием в стандартном режиме работы.

В статье я разберу:

  • Зачем клиентам хранить документацию в своей инфраструктуре.

  • Какие сложности это вызывает у компаний-разработчиков.

  • Как можно решить, чтобы все остались довольны.

Почему клиенты на этом настаивают

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

  • Быстрый доступ к данным. Локальное хранение документации ускоряет доступ к ней и уменьшает зависимость от внешних сетей и серверов. Также сотрудники клиента могут использовать единую учётную запись для аутентификации и в системе документации.

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

Какие сложности для нас — компании разработчика

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

  • Ограничения доступа. Сложно подключать новичков в команду, т.к. создание нового аккаунта в инфраструктуре клиента может занимать от нескольких недель до нескольких месяцев.

  • Разнообразие инструментов. Мы стремимся к унификации процесса разработки и использованию единых инструментов для работы. Если мы будем писать документацию в системах заказчика, то унификации не будет. Не получится хранить и версионировать документацию вместе с кодом.

Решение: Распределённое хранилище через Git

Git использует систему распределенного контроля версий, что означает, что каждый разработчик работает со своей локальной копией репозитория. Эта локальная копия содержит всю историю изменений: это позволяет работать с Git даже без постоянного доступа к интернету или центральному серверу. Если один из удаленных репозиториев будет потерян или поврежден, любой другой репозиторий может стать источником для восстановления всей истории.

Основные принципы работы:

  • Коммиты. Когда человек готов сохранить набор изменений, он создает «коммит». Этот коммит содержит информацию: что, кем и когда было изменено.

  • Push и Pull. Чтобы поделиться своими изменениями с другими или получить их изменения, используются операции  push  (для отправки своих коммитов в удаленный репозиторий) и  pull  (для получения коммитов из удаленного репозитория).

  • Обработка конфликтов. Если два человека вносят изменения в один и тот же файл одновременно, то Git указывает на конфликтующие участки текста и просит вручную разрешить конфликты.

Как применить к нашей задаче

  1. Развернуть в инфраструктуре клиента Git-хранилище с документацией.

  2. Настроить Git-зеркалирование с Git-хранилищем на стороне компании разработчика.

  3. Пользователи и поставщики услуг могут  работать в IDE с Markdown или использовать WYSIWYG для более удобной работы.

Что в итоге

Заказчик может проводить ревью изменений нашей документации и вносить собственные правки в базу знаний. А ещё может настроить ограничения доступа, чтобы только определённые участники могли редактировать или просматривать документы.

Проблема конфиденциальности не решается полностью, т.к. компания разработчик может выдать доступ кому угодно. Но и сейчас это никак не контролируется и документация хранится только у провайдера. А будет храниться и там, и там.