Документация в контуре заказчика
Привет! Меня зовут Александр Мачулин, я сооснователь Gramax и совладелец компании ics-it.
Мы разрабатываем аналитические системы для Pharma и FMCG-производителей. Наши клиенты в последнее время все чаще просят писать и хранить проектную документацию в их системах: Confluence, ServiceNow и т.д. При этом у нас процесс разработки документации построен через собственную систему с подходом Docs as Code. Потому поддержка документации в системе клиента будет дополнительным препятствием в стандартном режиме работы.
В статье я разберу:
Зачем клиентам хранить документацию в своей инфраструктуре.
Какие сложности это вызывает у компаний-разработчиков.
Как можно решить, чтобы все остались довольны.
Почему клиенты на этом настаивают
Безопасность. Хранение данных в инфраструктуре клиента может предоставить дополнительный уровень безопасности, т.к. у компаний строгие стандарты.
Быстрый доступ к данным. Локальное хранение документации ускоряет доступ к ней и уменьшает зависимость от внешних сетей и серверов. Также сотрудники клиента могут использовать единую учётную запись для аутентификации и в системе документации.
Конфиденциальность. Коммерческая или критическая информация должна быть доступна только определенному кругу лиц. Это проще всего реализовать, когда есть полный контроль над хранением данных.
Какие сложности для нас — компании разработчика
Аутентификация. Процесс входа и аутентификации, как правило, более сложный. Когда команда начинает работать над проектами разных заказчиков, то надо постоянно переключаться между аккаунтами.
Ограничения доступа. Сложно подключать новичков в команду, т.к. создание нового аккаунта в инфраструктуре клиента может занимать от нескольких недель до нескольких месяцев.
Разнообразие инструментов. Мы стремимся к унификации процесса разработки и использованию единых инструментов для работы. Если мы будем писать документацию в системах заказчика, то унификации не будет. Не получится хранить и версионировать документацию вместе с кодом.
Решение: распределённое хранилище через Git
Git использует систему распределенного контроля версий, что означает, что каждый разработчик работает со своей локальной копией репозитория. Эта локальная копия содержит всю историю изменений: это позволяет работать с Git даже без постоянного доступа к интернету или центральному серверу. Если один из удаленных репозиториев будет потерян или поврежден, любой другой репозиторий может стать источником для восстановления всей истории.
Основные принципы работы:
Коммиты. Когда человек готов сохранить набор изменений, он создает «коммит». Этот коммит содержит информацию: что, кем и когда было изменено.
Push и Pull. Чтобы поделиться своими изменениями с другими или получить их изменения, используются операции
push(для отправки своих коммитов в удаленный репозиторий) иpull(для получения коммитов из удаленного репозитория).Обработка конфликтов. Если два человека вносят изменения в один и тот же файл одновременно, то Git указывает на конфликтующие участки текста и просит вручную разрешить конфликты.
Как применить к нашей задаче
Развернуть в инфраструктуре клиента Git-хранилище с документацией.
Настроить Git-зеркалирование с Git-хранилищем на стороне компании разработчика.
Пользователи и поставщики услуг могут работать в IDE с Markdown или использовать WYSIWYG для более удобной работы.
Что в итоге
Заказчик может проводить ревью изменений нашей документации и вносить собственные правки в базу знаний. А ещё может настроить ограничения доступа, чтобы только определённые участники могли редактировать или просматривать документы.
Проблема конфиденциальности не решается полностью, т.к. компания разработчик может выдать доступ кому угодно. Но и сейчас это никак не контролируется и документация хранится только у провайдера. А будет храниться и там, и там.