Как DevOps практики меняют документацию
Как было
Disclaimer
Ниже описывается опыт сервисной компании по изгнанию большого объема скучной документации из проекта. Документация переведена в код. Автоматизированы многие процессы по развертыванию проекта. Начата работа по управлению знаниями.
Для продуктовых компаний опыт может быть нерелевантен. Да и все эти компания давно на ты с Knowledge Management.
Небольшой проект
Никакой документации нет. Есть только ТЗ. Информация об изменениях есть только в различных мессенджерах.
Найти информацию практически невозможно. Знания о проекте есть только у менеджера проекта и текущего разработчика.
Знаний накапливаются только в одной из голов. Обмен знаниями никак не налажен. Замена менеджера проекта или разработчика вели к существенной потере знаний о проекте. Привлечение нового разработчика в проект очень дорого.
Крупные проекты
Заказчик требует документацию:
- Руководство пользователя.
- Руководство администратора.
- Руководство разработчика.
Заказчик получает документацию в виде отдельных объемных документов. Эти документы создаются в редакторе типа Word. Документы получаются оторванными от реальности. Быстро устаревают.
Распространение знаний только через общение или чтение устаревшей документации. Привлечение нового разработчика в проект очень дорогое.
Что хотели получить
- Сократить время равертывания релиза.
- Снизить стоимость привлечения нового разработчика в проект.
- Наладить обмен знаниями.
- Поддерживать документацию в актуальном состоянии.
- Снизить обязательный объем документации к изучению.
Изменения
Причина изменений
- Начали работать над огромным для нас проектом.
- Привлечение к разработке новых сотрудников довольно дорогое.
- К продуктовому окружению команду разработки не подпускали. Развертывание может производить только отдел эксплуатации Заказчика.
- Квалификация сотрудников отдела эксплуатации крайне низкая.
- Заказчик требует документация по первоначальному развертыванию проекта и по выкатке доработок. Причем в этой документации должны быть учтены любые проблемы.
- Время развертывания приложения занимает несколько часов. Возможны даунтаймы.
Первые шаги
Вести разработку проекта стандартными способами было нельзя. А действие закона Конвея не давало сделать качественный проект по-новому.
Огромная сила воли помогла преодолеть все невзгоды и мы сделали почти работающий микросервисный продукт не изменяя компанию. Однако до нормального продукта ему было далеко и поэтому пришлось перенести команду этого продукта в отдельный офис. И уже там происходила трансформация команды и доработка продукта до приемлемого уровня качества.
Разработка документации
Разработка документации велась по этому проекту началась еще до начала разработки. Первоначально появилось верхнеуровневое описание архитектуры. Были описаны протоколы взаимодействия между микросервисами.
Развертывание проекта было описано достаточно подробно. Инструкция развертывания состояла из множества шагов. Но описать все возможные случаи практически невозможно. Развертывание каждого нового релиза длилось очень долго. Всегда возникала какая-то новая проблема.
Привлечение новых разработчиков
Проект рос и приходилось привлекать новых разработчиков.
Распространение знаний только через общение или чтение документации. К счастью документация поддерживалась в актуальном состоянии.
Развертывание проекта на компьютере разработчика долгое. Всегда сопровождалось кучей проблем. В среднем развертывание занимало 2-3 часа с обязательным привлечением тимлида.
Решение
Развертывание проекта для разработчиков
Необходимо снизить объем документации, которую должен изучить разработчик для развертывания проекта у себя. Причем она должна оставаться актуальной. Документация перемещается в код и становится кодом.
Dockerfile, docker-compose
Все необходимое окружение описано в Dockerfile и docker-compose. Развертывание проекта становится более простой задачей, но все таки нужно сделать несколько предварительных шагов.
Makefile
Снижает количество предварительных шагов до минимума. В коде описаны все шаги для старта работы над приложением.
Время развертывания снизилось до 5 минут. Привлечение тимлида больше не нужно. Число шагов в инструкции по развертыванию снизилось с 15 до 4.
Развертывание проекта для эксплуатации
Первоначально сборкой занимались вручную сами разработчики. Причем часто получалось, что пересобирался не весь проект.
Для решения этой проблемы выделена отдельная build машина, на которой происходит сборка образов и пуш их в приватный docker registry. Приложение разворачивается из готовых образов.
Сборка может занимать 5-10 минут. Развертывание из образов происходит менее чем за 1 минуту. При этом даунтаймов не наблюдается. Такой подход все еще представляет из себя многоходовочку. Но число шагов уже намного меньше. Все инструкции по сборке и развертыванию переместились в Makefile. Аварийные развертывания остались в прошлом.
Такой вариант нас тоже не устраивает до конца. Поэтому следующим шагом будет автоматизация билдов и развертывания с помощью pipeline Gitlab CI/CD.
Результат
- Разработчик может развернуть проект достаточно быстро.
- Эксплуатант накатывает новые версии. Ошибок не возникает.
Объем знаний, которые нужно получать для успешного развертывания, сведен к минимуму.
При этом документация не исчезла. Она просто перекочевала в код. Такого рода документацию пишет разработчик. Она поддерживается в актуальном состоянии. При желании разработчик может легко разобраться с таким кодом. Это гораздо приятнее, чем читать документацию. В результате он получает новые знания и легко перенести на другой проект.
Этот опыт сейчас активно переносится на другие проекты. В результате ускоряются релизы и начали улучшаться другие процессы Knowledge Management. Причем инициаторами таких изменений становятся рядовые сотрудники.